@framesquared/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1246 @@
+/**
+ * @framesquared/core – utility functions
+ *
+ * Pure, side-effect-free helpers (except timer wrappers and generateId).
+ * Every function is individually exported so tree-shaking works out of the box.
+ */
+/**
+ * Returns the value unchanged. Useful as a default transform or callback.
+ */
+declare function identity<T>(value: T): T;
+/**
+ * A reusable no-op function.
+ */
+declare function emptyFn(): void;
+/**
+ * Copies **own** enumerable properties from `source` to `target`,
+ * but only when the property does **not** already exist on `target`
+ * (checked via the `in` operator so even `undefined` values are preserved).
+ *
+ * Returns the mutated `target`.
+ */
+declare function applyIf<T extends object>(target: T, source: Partial<T>): T;
+/**
+ * Copies **own** enumerable properties from every `source` to `target`,
+ * overwriting any existing values.  Sources are applied left-to-right so
+ * later sources win.
+ *
+ * Returns the mutated `target`.
+ */
+declare function apply<T extends object>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Deep-clones `value` using the platform's `structuredClone`.
+ */
+declare function clone<T>(value: T): T;
+/**
+ * `true` for plain objects only — `{}`, `Object.create(null)`, and objects
+ * whose prototype is `Object.prototype`.  Returns `false` for arrays,
+ * functions, `null`, class instances (`Date`, `RegExp`, …), and primitives.
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * `true` for primitive `string` values only (not `String` wrapper objects).
+ */
+declare function isString(value: unknown): value is string;
+/**
+ * `true` for finite numbers and `±Infinity`.  Explicitly **excludes** `NaN`.
+ */
+declare function isNumber(value: unknown): value is number;
+/**
+ * `true` for primitive `boolean` values only (not `Boolean` wrapper objects).
+ */
+declare function isBoolean(value: unknown): value is boolean;
+/**
+ * `true` for any callable — arrows, named functions, async functions,
+ * generators, and class constructors.
+ */
+declare function isFunction(value: unknown): value is Function;
+/**
+ * Thin wrapper around `Array.isArray` with an `unknown[]` return type.
+ */
+declare function isArray(value: unknown): value is unknown[];
+/**
+ * `true` when `value` is neither `undefined` nor `null`.
+ */
+declare function isDefined<T>(value: T | undefined | null): value is T;
+/**
+ * `true` for values that are conceptually "empty":
+ * `undefined`, `null`, `''`, `[]`, `{}` (plain, no own keys), and `NaN`.
+ */
+declare function isEmpty(value: unknown): boolean;
+/**
+ * `true` when `value` implements the iterable protocol (`Symbol.iterator`).
+ * Returns `false` for `null`, `undefined`, and non-iterable objects.
+ */
+declare function isIterable(value: unknown): value is Iterable<unknown>;
+/**
+ * `true` for all seven primitive types:
+ * `string`, `number`, `boolean`, `undefined`, `null`, `symbol`, and `bigint`.
+ */
+declare function isPrimitive(value: unknown): boolean;
+/**
+ * Walks (and lazily creates) a dot-separated namespace on `root`.
+ *
+ * ```ts
+ * const root = {};
+ * namespace(root, 'a.b.c'); // root is now { a: { b: { c: {} } } }
+ * ```
+ *
+ * Existing intermediate objects are preserved; only missing segments are
+ * created as empty plain objects.  Returns the **leaf** object.
+ */
+declare function namespace(root: object, path: string): object;
+/**
+ * Wrapper around `setTimeout` that returns the numeric timer id.
+ */
+declare function defer(fn: () => void, millis?: number): number;
+/**
+ * Wrapper around `setInterval` that returns the numeric timer id.
+ */
+declare function interval(fn: () => void, millis: number): number;
+/**
+ * High-resolution timestamp via `performance.now()`.
+ */
+declare function now(): number;
+/**
+ * Generates a globally-unique ID string.  The counter is monotonically
+ * increasing across all prefixes.
+ *
+ * ```ts
+ * generateId();          // "framesquared-1"
+ * generateId();          // "framesquared-2"
+ * generateId('widget');  // "widget-3"
+ * ```
+ */
+declare function generateId(prefix?: string): string;
+
+/**
+ * @framesquared/core – String utilities
+ */
+/**
+ * Capitalizes the first character of `str`.
+ */
+declare function capitalize(str: string): string;
+/**
+ * Lowercases the first character of `str`.
+ */
+declare function uncapitalize(str: string): string;
+/**
+ * Truncates `value` to `length` characters (including a trailing `"…"` when
+ * truncation occurs).  When `word` is `true` the cut happens before the last
+ * whitespace boundary so words are not split mid-way.
+ */
+declare function ellipsis(value: string, length: number, word?: boolean): string;
+/**
+ * Escapes `&`, `<`, `>`, `"`, and `'` to their HTML entity equivalents.
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Reverses {@link escapeHtml}, converting HTML entities back to characters.
+ */
+declare function unescapeHtml(str: string): string;
+/** Alias for {@link escapeHtml}. */
+declare const htmlEncode: typeof escapeHtml;
+/** Alias for {@link unescapeHtml}. */
+declare const htmlDecode: typeof unescapeHtml;
+/**
+ * Escapes all RegExp-special characters so the result can be used inside
+ * `new RegExp(...)` to match the literal string.
+ */
+declare function escapeRegex(str: string): string;
+/**
+ * Replaces `{0}`, `{1}`, … placeholders in `template` with the
+ * corresponding positional values (converted via `String()`).
+ */
+declare function format(template: string, ...values: unknown[]): string;
+/**
+ * Repeats `str` exactly `count` times.
+ */
+declare function repeat(str: string, count: number): string;
+/**
+ * Trims leading and trailing whitespace.
+ */
+declare function trim(str: string): string;
+/**
+ * Left-pads `str` to `size` characters using `char` (default `' '`).
+ * Only the first character of `char` is used.
+ */
+declare function leftPad(str: string, size: number, char?: string): string;
+/**
+ * Returns `value2` when `str === value1`, otherwise returns `value1`.
+ */
+declare function toggle(str: string, value1: string, value2: string): string;
+/**
+ * Splits a string into its constituent words, recognising camelCase,
+ * PascalCase, snake_case, and kebab-case boundaries.
+ *
+ * Consecutive uppercase letters are treated as a single acronym, e.g.
+ * `"parseHTMLString"` → `["parse", "HTML", "String"]`.
+ */
+declare function splitWords(str: string): string[];
+/**
+ * Converts a string to `camelCase`.
+ */
+declare function camelCase(str: string): string;
+/**
+ * Converts a string to `kebab-case`.
+ */
+declare function kebabCase(str: string): string;
+/**
+ * Converts a string to `PascalCase`.
+ */
+declare function pascalCase(str: string): string;
+
+/**
+ * @framesquared/core – Array utilities
+ */
+/**
+ * Normalizes a value to an array.
+ *
+ * - If already an array, returns it as-is (same reference).
+ * - If an iterable (but not a string), spreads it into a new array.
+ * - Otherwise wraps it in a single-element array.
+ *
+ * Strings are intentionally *not* spread into characters — `from("hi")`
+ * returns `["hi"]`, not `["h","i"]`.
+ */
+declare function from<T>(value: T | T[] | Iterable<T>): T[];
+/**
+ * Returns `true` if `array` contains `item`, using `Array.prototype.includes`
+ * (which handles `NaN`).
+ */
+declare function contains<T>(array: T[], item: T): boolean;
+/**
+ * Adds `item` to `array` if it is not already present.  Mutates and returns
+ * the same array reference.
+ */
+declare function include<T>(array: T[], item: T): T[];
+/**
+ * Removes the **first** occurrence of `item` from `array`.  Mutates and
+ * returns the same array reference.
+ */
+declare function remove<T>(array: T[], item: T): T[];
+/**
+ * Returns a **new** array with all `null` and `undefined` entries removed.
+ */
+declare function clean<T>(array: (T | null | undefined)[]): T[];
+/**
+ * Returns a **new** array with duplicate values removed, preserving the order
+ * of first occurrence.  Uses a `Set` (strict/reference equality).
+ */
+declare function unique<T>(array: T[]): T[];
+/**
+ * Flattens one level deep: `[1, [2, 3], 4]` → `[1, 2, 3, 4]`.
+ * Does **not** recurse into deeper nesting.
+ */
+declare function flatten<T>(array: (T | T[])[]): T[];
+/**
+ * Extracts the value of `key` from every element.
+ */
+declare function pluck<T, K extends keyof T>(array: T[], key: K): T[K][];
+/**
+ * Returns the sum of all elements.  Returns `0` for an empty array.
+ */
+declare function sum(array: number[]): number;
+/**
+ * Returns the arithmetic mean.  Returns `NaN` for an empty array.
+ */
+declare function mean(array: number[]): number;
+/**
+ * Returns the minimum element.  When no `compareFn` is given, uses `<`.
+ * Throws if the array is empty.
+ */
+declare function min<T>(array: T[], compareFn?: (a: T, b: T) => number): T;
+/**
+ * Returns the maximum element.  When no `compareFn` is given, uses `<`.
+ * Throws if the array is empty.
+ */
+declare function max<T>(array: T[], compareFn?: (a: T, b: T) => number): T;
+/**
+ * Groups elements by the string/number key returned by `fn`.
+ */
+declare function groupBy<T, K extends string | number>(array: T[], fn: (item: T) => K): Record<K, T[]>;
+/**
+ * Splits an array into two: elements that satisfy the predicate and those
+ * that don't.
+ */
+declare function partition<T>(array: T[], predicate: (item: T) => boolean): [T[], T[]];
+/**
+ * Splits `array` into chunks of at most `size` elements.
+ * Throws if `size` is ≤ 0.
+ */
+declare function chunk<T>(array: T[], size: number): T[][];
+/**
+ * Returns elements in `array1` that are **not** in `array2`.
+ */
+declare function difference<T>(array1: T[], array2: T[]): T[];
+/**
+ * Returns elements that appear in **both** `array1` and `array2`, preserving
+ * order from `array1`.  Each value appears at most once in the result.
+ */
+declare function intersection<T>(array1: T[], array2: T[]): T[];
+/**
+ * Returns a **new** sorted array.  `key` may be a property name or an
+ * accessor function.  Default direction is `'ASC'`.
+ */
+declare function sortBy<T>(array: T[], key: keyof T | ((item: T) => unknown), direction?: 'ASC' | 'DESC'): T[];
+/**
+ * Returns the first element for which `fn` returns `true`, or `undefined`.
+ */
+declare function findBy<T>(array: T[], fn: (item: T) => boolean): T | undefined;
+/**
+ * Generates a half-open range `[start, end)` with the given `step`
+ * (default `1`).  A negative step produces a descending range.
+ * Throws if `step` is `0`.
+ */
+declare function range(start: number, end: number, step?: number): number[];
+
+/**
+ * @framesquared/core – Object utilities
+ */
+/**
+ * Typed wrapper around `Object.keys`.
+ */
+declare function keys<T extends object>(obj: T): (keyof T)[];
+/**
+ * Typed wrapper around `Object.values`.
+ */
+declare function values<T extends object>(obj: T): T[keyof T][];
+/**
+ * Typed wrapper around `Object.entries`.
+ */
+declare function entries<T extends object>(obj: T): [keyof T, T[keyof T]][];
+/**
+ * Typed wrapper around `Object.fromEntries`.
+ */
+declare function fromEntries<K extends string, V>(items: [K, V][]): Record<K, V>;
+/**
+ * Deep-merges own enumerable properties from every `source` into `target`.
+ *
+ * - Plain objects are recursively merged.
+ * - Arrays and non-plain objects are **overwritten** (not merged element-wise).
+ * - Mutates and returns `target`.
+ */
+declare function merge<T extends object>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Returns a new object containing only the specified `pickedKeys`.
+ */
+declare function pick<T extends object, K extends keyof T>(obj: T, pickedKeys: K[]): Pick<T, K>;
+/**
+ * Returns a new object with the specified `omittedKeys` removed.
+ */
+declare function omit<T extends object, K extends keyof T>(obj: T, omittedKeys: K[]): Omit<T, K>;
+/**
+ * Returns a new object with every value transformed by `fn`.
+ */
+declare function mapValues<T extends object, U>(obj: T, fn: (value: T[keyof T], key: keyof T) => U): Record<keyof T, U>;
+/**
+ * Returns a new object with every key transformed by `fn`.
+ */
+declare function mapKeys<T extends object>(obj: T, fn: (key: keyof T) => string): Record<string, T[keyof T]>;
+/**
+ * Recursively freezes `obj` and all nested objects / arrays.
+ * Returns the same reference.
+ */
+declare function freeze<T extends object>(obj: T): Readonly<T>;
+/**
+ * Deep structural equality comparison.  Handles primitives, plain objects,
+ * arrays, `Date`, `RegExp`, and `NaN`.
+ */
+declare function equals(a: unknown, b: unknown): boolean;
+/**
+ * Traverses `obj` along the dot-separated `path` and returns the value found.
+ * Returns `defaultValue` when the path does not exist (i.e. an intermediate
+ * segment is missing).  If the final property exists but its value is
+ * `undefined`, `undefined` is returned (not `defaultValue`).
+ */
+declare function getNestedValue(obj: object, path: string, defaultValue?: unknown): unknown;
+/**
+ * Sets a value at a dot-separated `path`, creating intermediate objects as
+ * needed.
+ */
+declare function setNestedValue(obj: object, path: string, value: unknown): void;
+/**
+ * Flattens a nested object into a single-level object with dot-separated keys.
+ *
+ * Arrays and non-plain objects are treated as leaf values (not recursed into).
+ */
+declare function flattenObject(obj: object, prefix?: string): Record<string, unknown>;
+/**
+ * Reverse of {@link flattenObject}: expands dot-separated keys into a nested
+ * object.
+ */
+declare function unflattenObject(obj: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * @framesquared/core – Function utilities
+ */
+/**
+ * Binds `fn` to `scope` with optional pre-filled arguments.
+ */
+declare function bind<T extends Function>(fn: T, scope: unknown, ...args: unknown[]): T;
+/**
+ * Returns a function that delays invoking `fn` until `buffer` milliseconds
+ * have elapsed since the **last** call.  Each new call resets the timer
+ * (classic debounce).
+ */
+declare function createBuffered(fn: Function, buffer: number, scope?: unknown): (...args: unknown[]) => void;
+/**
+ * Returns a function that always delays invoking `fn` by `delay` ms.
+ * Each call schedules its **own** independent timer (unlike debounce).
+ */
+declare function createDelayed(fn: Function, delay: number, scope?: unknown): (...args: unknown[]) => void;
+/**
+ * Returns a function that invokes `fn` at most once per `intervalMs`
+ * milliseconds.  The first call executes immediately.
+ */
+declare function createThrottled(fn: Function, intervalMs: number, scope?: unknown): (...args: unknown[]) => void;
+/**
+ * Returns a function that only invokes `fn` once the returned function has
+ * been called exactly `count` times.  Subsequent calls are no-ops.
+ */
+declare function createBarrier(count: number, fn: Function, scope?: unknown): (...args: unknown[]) => void;
+/**
+ * Replaces `obj[methodName]` with a wrapper that calls `fn` **before** the
+ * original method.  `fn` receives the same arguments as the original.
+ */
+declare function interceptBefore(obj: object, methodName: string, fn: Function): void;
+/**
+ * Replaces `obj[methodName]` with a wrapper that calls `fn` **after** the
+ * original method.  `fn` receives the original method's return value as its
+ * single argument.  The wrapper still returns the original return value.
+ */
+declare function interceptAfter(obj: object, methodName: string, fn: Function): void;
+/**
+ * Returns a function that calls every function in `fns` in order, passing
+ * all received arguments to each.
+ */
+declare function createSequence(...fns: Function[]): (...args: unknown[]) => void;
+/**
+ * Returns a memoized version of `fn`.  By default the first argument
+ * (stringified) is used as the cache key.  Supply a `hasher` for
+ * multi-argument or non-primitive keys.
+ */
+declare function memoize<T extends (...args: any[]) => any>(fn: T, hasher?: (...args: Parameters<T>) => string): T;
+/**
+ * Returns a function that invokes `fn` at most once.  Subsequent calls
+ * return the result of the first invocation.
+ */
+declare function once<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * Returns a function that negates the boolean return value of `fn`.
+ */
+declare function negate<T extends (...args: any[]) => boolean>(fn: T): T;
+/**
+ * Right-to-left function composition.
+ * `compose(f, g, h)(x)` is equivalent to `f(g(h(x)))`.
+ */
+declare function compose(...fns: Function[]): (...args: unknown[]) => unknown;
+/**
+ * Left-to-right function composition (aka pipeline).
+ * `pipe(f, g, h)(x)` is equivalent to `h(g(f(x)))`.
+ */
+declare function pipe(...fns: Function[]): (...args: unknown[]) => unknown;
+
+/**
+ * @framesquared/core – Base class
+ *
+ * Foundation for the framesquared class system.  Provides:
+ *  - Config auto-generation (getX / setX / applyX / updateX lifecycle)
+ *  - callParent() for wrapped methods (set up by define())
+ *  - destroy() + Symbol.dispose
+ *  - Mixin tracking via hasMixin()
+ */
+/** Per-instance call-stack entries for callParent(). */
+interface CallStackEntry {
+    methodName: string;
+    owner: typeof Base;
+}
+declare class Base {
+    /** Fully-qualified class name. */
+    static $className: string;
+    /** Merged config defaults for this class (populated by processClassConfigs). */
+    static $configDefs: Record<string, unknown>;
+    /** Set of mixin constructors applied to this class (populated by define). */
+    static $mixins: Set<typeof Base>;
+    /** Per-instance call-stack used by `callParent()`. */
+    $callStack: CallStackEntry[];
+    /** Tracks which config properties have been explicitly initialized. */
+    $configInitialized: Set<string>;
+    /**
+     * Raw config object passed to the constructor.  Decorator-based configs
+     * are consumed from here by `addInitializer` callbacks (which run after
+     * auto-accessor field initialization).
+     */
+    $pendingConfig: Record<string, unknown> | undefined;
+    /** Whether `destroy()` has been called. */
+    isDestroyed: boolean;
+    /**
+     * Array of cleanup callbacks.  Mixins (and user code) can push
+     * functions here; they all run during `destroy()`.
+     */
+    $destroyHooks: (() => void)[];
+    /** The fully-qualified class name of this instance's constructor. */
+    get $className(): string;
+    /** Reference to the constructor (like ExtJS's `this.self`). */
+    get self(): typeof Base;
+    constructor(config?: Record<string, unknown>);
+    /**
+     * Static factory — creates an instance of the class.
+     */
+    static create(this: new (...a: any[]) => Base, ...args: any[]): Base;
+    /**
+     * Applies the given config properties to this instance.  Ensures that
+     * config accessors have been generated for the class first.
+     */
+    initConfig(config?: Record<string, unknown>): void;
+    /**
+     * Calls the parent (super) class's implementation of the method that is
+     * currently executing.  Only works for methods wrapped via `define()`.
+     */
+    callParent(args?: unknown[]): unknown;
+    /**
+     * Returns `true` if the given mixin has been applied to this class (or
+     * to any of its ancestors / other mixins).
+     */
+    hasMixin(mixin: typeof Base): boolean;
+    /**
+     * Tears down this instance.  Calls `onDestroy()` if defined.
+     * Idempotent — second and subsequent calls are no-ops.
+     */
+    destroy(): void;
+    /**
+     * `Symbol.dispose` support — calling `[Symbol.dispose]()` is equivalent
+     * to `destroy()`, enabling the TC39 `using` keyword.
+     */
+    [Symbol.dispose](): void;
+}
+
+/**
+ * @framesquared/core – ClassManager + define()
+ *
+ * Central registry for framesquared classes and the `define()` factory that
+ * creates, configures, and registers new classes in a single call.
+ */
+
+interface ClassDefinition {
+    /** Parent class (defaults to Base). */
+    extend?: typeof Base;
+    /** Mixins to apply. */
+    mixins?: (typeof Base)[];
+    /** One or more alias strings for ClassManager lookup. */
+    alias?: string | string[];
+    /** Config property defaults (auto-generates getX / setX). */
+    config?: Record<string, unknown>;
+    /** Static members to copy onto the constructor. */
+    statics?: Record<string, unknown>;
+    /** Any other properties are treated as prototype methods / members. */
+    [key: string]: unknown;
+}
+declare class ClassManagerImpl {
+    /** className → constructor */
+    private classes;
+    /** alias → constructor */
+    private aliases;
+    register(name: string, cls: typeof Base): void;
+    get(name: string): typeof Base | undefined;
+    getByAlias(alias: string): typeof Base | undefined;
+    isRegistered(name: string): boolean;
+    /**
+     * Returns all registered class names that start with `prefix`.
+     */
+    getNamesByPrefix(prefix: string): string[];
+    /**
+     * Creates an instance by alias, passing remaining args to the constructor.
+     */
+    instantiateByAlias(alias: string, ...args: any[]): Base;
+    registerAlias(alias: string, cls: typeof Base): void;
+}
+/** Singleton instance. */
+declare const ClassManager: ClassManagerImpl;
+/**
+ * Creates a new class, applies mixins, sets up config accessors, wraps
+ * methods for `callParent()`, registers with {@link ClassManager}, and
+ * returns the ready-to-use constructor.
+ *
+ * ```ts
+ * const Button = define('ui.Button', {
+ *   extend: Component,
+ *   mixins: [Focusable],
+ *   alias: 'widget.button',
+ *   config: { text: '', disabled: false },
+ *   onClick() { ... },
+ * });
+ * ```
+ */
+declare function define(className: string, definition: ClassDefinition): typeof Base;
+
+/**
+ * @framesquared/core – Configurator
+ *
+ * Central metadata registry for the `@config` decorator family.
+ * Uses TC39 `context.metadata` (Symbol.metadata) so metadata is
+ * available immediately after class definition — no instance needed.
+ */
+interface ConfigMeta {
+    /** Property name. */
+    name: string;
+    /** True when the config MUST be provided at construction time. */
+    required: boolean;
+    /** Factory function for lazy configs (computed on first access). */
+    lazyFactory?: (this: any) => unknown;
+    /** True when the getter result should be cached until next set. */
+    cached: boolean;
+    /** True when object values should be deep-merged with defaults. */
+    merge: boolean;
+    /** True when a change event should fire (Phase 2 integration). */
+    observable: boolean;
+}
+declare class ConfiguratorImpl {
+    /**
+     * Returns the ConfigMeta for a single config on the given class,
+     * walking the prototype chain.
+     */
+    getConfigMeta(Ctor: Function, configName: string): ConfigMeta | undefined;
+    /**
+     * Collects all ConfigMeta entries for `Ctor`, including inherited.
+     */
+    getAllConfigMeta(Ctor: Function): ConfigMeta[];
+}
+/** Singleton. */
+declare const Configurator: ConfiguratorImpl;
+
+/**
+ * @framesquared/core – TC39 Stage 3 decorators
+ *
+ * Usage:
+ * ```ts
+ * @alias('widget.panel')
+ * @mixin(Draggable)
+ * class Panel extends Base {
+ *   @config            accessor title: string = 'Untitled';
+ *   @config.required   accessor id: string = '';
+ *   @config.lazy(fn)   accessor data: object = {};
+ *   @config.cached     accessor fullName: string = '';
+ *   @config.merge      accessor style: object = {};
+ *   @observable @config accessor theme: string = 'light';
+ * }
+ * ```
+ */
+
+interface ConfigDecorator {
+    <This extends Base, Value>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): ClassAccessorDecoratorResult<This, Value>;
+    required: <This extends Base, Value>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value>;
+    lazy: (factory: (this: any) => unknown) => <This extends Base, Value>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value>;
+    cached: <This extends Base, Value>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value>;
+    merge: <This extends Base, Value>(target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value>;
+}
+declare const config: ConfigDecorator;
+/**
+ * Marks a `@config` accessor as observable.  Stores metadata only;
+ * event firing is Phase 2.
+ */
+declare function observable<This extends Base, Value>(_target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>): void;
+declare function alias(aliasName: string): <T extends abstract new (...args: any[]) => any>(target: T, _context: ClassDecoratorContext<T>) => T;
+declare function mixin(mixinClass: typeof Base): <T extends abstract new (...args: any[]) => any>(target: T, _context: ClassDecoratorContext<T>) => T;
+declare function override(targetClass: typeof Base): <T extends abstract new (...args: any[]) => any>(patchClass: T, _context: ClassDecoratorContext<T>) => T;
+
+/**
+ * @framesquared/core – Identifiable mixin
+ *
+ * Adds an `id` config to any class.  If no id is provided, one is
+ * auto-generated via `generateId()`.  Instances are registered in a
+ * global {@link IdentityMap} for lookup by id and automatically
+ * removed on destroy.
+ */
+
+declare class IdentityMapImpl {
+    private map;
+    register(id: string, instance: Base): void;
+    unregister(id: string): void;
+    get(id: string): Base | undefined;
+    has(id: string): boolean;
+}
+/** Singleton global identity map. */
+declare const IdentityMap: IdentityMapImpl;
+declare const Identifiable: typeof Base;
+
+/**
+ * @framesquared/core – Factoryable
+ *
+ * Static factory that creates `Base` instances from flexible input:
+ *
+ * - Config object with `xtype` or `type` → alias lookup via ClassManager
+ * - Plain string → treated as an alias
+ * - Existing Base instance → returned as-is
+ */
+
+declare const Factoryable: {
+    /**
+     * Creates a `Base` instance from a config descriptor.
+     *
+     * @param config  An object with `xtype`/`type`, a string alias, or
+     *                an existing `Base` instance.
+     */
+    create(config: string | Base | Record<string, any>): Base;
+};
+
+/**
+ * @framesquared/core – Inheritable mixin
+ *
+ * Provides hierarchical parent → child config inheritance.  Each instance
+ * can have an "inherited parent" whose inherited state is merged with the
+ * instance's own inherited state.  Lookup walks up the chain.
+ */
+
+declare const Inheritable: typeof Base;
+
+/**
+ * @framesquared/core – Hookable mixin
+ *
+ * Provides per-instance before/after hook points for any method.
+ * Hooks fire in registration order.  Adding a hook wraps the method
+ * on the instance (not the prototype), so other instances are unaffected.
+ */
+
+declare const Hookable: typeof Base;
+
+/**
+ * @framesquared/core – Pluggable mixin
+ *
+ * Adds plugin management to any class.  Plugins are instantiated from
+ * config objects (using Factoryable semantics) or accepted as instances.
+ * All plugins are destroyed when the owner is destroyed.
+ */
+
+declare const Pluggable: typeof Base;
+
+/**
+ * @framesquared/core – Plugin base class
+ *
+ * Base class for plugins used with the Pluggable mixin.
+ * Each plugin has an `id`, an `init(owner)` lifecycle hook, and
+ * is destroyed when its owner is destroyed.
+ */
+
+/**
+ * Declare the config-generated methods so TypeScript knows about them.
+ */
+interface Plugin {
+    getId(): string;
+    setId(id: string): void;
+    getOwner(): Base | null;
+    setOwner(owner: Base | null): void;
+}
+declare class Plugin extends Base {
+    static $className: string;
+    static $configDefs: Record<string, unknown>;
+    /**
+     * Initialises this plugin.  Called by the Pluggable mixin after the
+     * plugin is added to an owner.
+     */
+    init(owner: Base): void;
+    /**
+     * Override of initConfig that ensures an auto-generated id.
+     */
+    initConfig(config?: Record<string, unknown>): void;
+}
+
+/**
+ * @framesquared/core – ExtEvent
+ *
+ * Represents a fired event.  Provides `preventDefault()`,
+ * `stopPropagation()`, and `stopEvent()` controls.
+ */
+declare class ExtEvent {
+    readonly eventName: string;
+    readonly source: unknown;
+    readonly timestamp: number;
+    defaultPrevented: boolean;
+    propagationStopped: boolean;
+    constructor(eventName: string, source: unknown);
+    preventDefault(): void;
+    stopPropagation(): void;
+    /** Convenience: prevents default AND stops propagation. */
+    stopEvent(): void;
+}
+
+/**
+ * @framesquared/core – Observable mixin
+ *
+ * The event system backbone.  Mix into any Base subclass to gain full
+ * event management: `on`, `un`, `fireEvent`, suspend/resume, relay,
+ * managed listeners, and more.
+ */
+
+interface ListenerOptions {
+    /** Fire only once, then auto-remove. */
+    single?: boolean;
+    /** Delay in ms before the handler is called. */
+    delay?: number;
+    /** Buffer (debounce) in ms — resets on each fire. */
+    buffer?: number;
+    /** Higher priority fires first. Default is 0. */
+    priority?: number;
+    /** Extra arguments prepended to handler call. */
+    args?: unknown[];
+    /** Insert at front within the same priority band. */
+    prepend?: boolean;
+    /** Return a Destroyable handle from `on()`. */
+    destroyable?: boolean;
+}
+declare const Observable: typeof Base;
+
+/**
+ * @framesquared/core – Destroyable
+ *
+ * Interface for objects that support deterministic cleanup, plus a
+ * utility to combine multiple destroyables into one.
+ */
+interface Destroyable {
+    destroy(): void;
+}
+declare const DestroyableUtil: {
+    /**
+     * Returns a single {@link Destroyable} whose `destroy()` method calls
+     * `destroy()` on every item.  The combined handle is idempotent — second
+     * and subsequent calls are no-ops.
+     */
+    combine(...items: Destroyable[]): Destroyable;
+};
+
+/**
+ * @framesquared/core – EventDomain
+ *
+ * A domain groups events by category (e.g. 'component', 'store').
+ * Controllers can use `domain.listen({ '#myButton': { click: handler } })`
+ * to route events by selector.
+ *
+ * Selectors:
+ *  - `#itemId`  — matches target.getItemId() === 'itemId'
+ *  - `ClassName` — matches target.$className === 'ClassName'
+ */
+
+/** Selector → { eventName → handler } */
+type ListenerConfig = Record<string, Record<string, Function>>;
+declare class EventDomain {
+    readonly name: string;
+    private readonly matchFn;
+    private registeredListeners;
+    constructor(name: string, matchFn: (target: Base) => boolean);
+    static register(name: string, domain: EventDomain): void;
+    static get(name: string): EventDomain | undefined;
+    /**
+     * Returns `true` if `target` belongs to this domain.
+     */
+    match(target: Base): boolean;
+    /**
+     * Registers a controller-style listener config.
+     *
+     * ```ts
+     * domain.listen({
+     *   '#myButton': { click: handler },
+     *   'MyApp.view.Panel': { collapse: handler },
+     * });
+     * ```
+     *
+     * Returns a {@link Destroyable} that removes all registered listeners.
+     */
+    listen(config: ListenerConfig): Destroyable;
+    /**
+     * Dispatches an event from `source` through this domain.
+     * All registered listeners whose selector matches are called.
+     */
+    dispatch(source: Base, eventName: string, args: unknown[]): void;
+    private matchesSelector;
+}
+
+/**
+ * @framesquared/core – EventBus
+ *
+ * Global singleton event bus with publish / subscribe semantics.
+ * Supports dot-separated namespaced channels and wildcards:
+ *
+ *  - `"user.login"`     — exact match
+ *  - `"user.*"`         — matches one segment after "user."
+ *  - `"user.**"`        — matches one or more segments after "user."
+ *  - `"**"`             — matches any channel
+ */
+
+declare class EventBusImpl {
+    private subscriptions;
+    /**
+     * Publishes a message to a channel.  All matching subscribers are called.
+     */
+    publish(channel: string, ...args: unknown[]): void;
+    /**
+     * Subscribes to a channel (exact or wildcard pattern).
+     * Returns a {@link Destroyable} handle.
+     */
+    subscribe(channel: string, handler: Function, scope?: object): Destroyable;
+    /**
+     * Removes a specific subscription by handler reference.
+     */
+    unsubscribe(channel: string, handler: Function): void;
+}
+/** Singleton global event bus. */
+declare const EventBus: EventBusImpl;
+
+/**
+ * @framesquared/core – TypedObservable
+ *
+ * A generic interface that overlays type-safe event signatures on top
+ * of the runtime Observable mixin.
+ *
+ * Usage:
+ * ```ts
+ * interface PanelEvents {
+ *   expand:   [panel: Panel];
+ *   collapse: [panel: Panel];
+ *   resize:   [panel: Panel, width: number, height: number];
+ *   close:    [];
+ * }
+ *
+ * class Panel extends Base implements TypedObservable<PanelEvents> { ... }
+ *
+ * const p = new Panel();
+ * p.on('resize', (panel, width, height) => { ... }); // fully typed
+ * p.fireEvent('resize', p, 100, 200);                // args checked
+ * ```
+ *
+ * The interface only constrains the type checker — at runtime the
+ * untyped Observable methods are used.
+ */
+
+/**
+ * Constraint for event maps.  Every key must map to a tuple of handler
+ * argument types.  Works with both `type` aliases and `interface`s.
+ *
+ * ```ts
+ * interface MyEvents {
+ *   click: [x: number, y: number];
+ *   load:  [];
+ * }
+ * ```
+ */
+type EventMap = {};
+/**
+ * Overlay interface that narrows Observable's string-based API to a
+ * concrete event map `Events`.
+ */
+interface TypedObservable<Events extends {
+    [K in keyof Events]: unknown[];
+}> {
+    on<E extends keyof Events & string>(eventName: E, handler: (...args: Events[E]) => void | false, scope?: object, options?: ListenerOptions): Destroyable | void;
+    un<E extends keyof Events & string>(eventName: E, handler: (...args: Events[E]) => void | false, scope?: object): void;
+    addListener<E extends keyof Events & string>(eventName: E, handler: (...args: Events[E]) => void | false, scope?: object, options?: ListenerOptions): Destroyable | void;
+    removeListener<E extends keyof Events & string>(eventName: E, handler: (...args: Events[E]) => void | false, scope?: object): void;
+    fireEvent<E extends keyof Events & string>(eventName: E, ...args: Events[E]): boolean;
+    fireEventArgs<E extends keyof Events & string>(eventName: E, args: Events[E]): boolean;
+    hasListener<E extends keyof Events & string>(eventName: E): boolean;
+}
+
+/**
+ * @framesquared/core – EventManager (DomEvent)
+ *
+ * Thin layer over native DOM events providing:
+ *  - Tracked listener registration with bulk cleanup
+ *  - Event delegation via closest()
+ *  - DOM-ready callback
+ *  - Utility helpers for coordinates, keys, stopEvent
+ */
+
+declare const EventManager: {
+    /**
+     * Registers a DOM event listener.  The listener is tracked for
+     * bulk removal via {@link removeAll}.
+     *
+     * Returns a {@link Destroyable} handle.
+     */
+    on(element: Element | Document, eventName: string, handler: EventListener, options?: AddEventListenerOptions): Destroyable;
+    /**
+     * Removes a DOM event listener.
+     */
+    un(element: Element | Document, eventName: string, handler: EventListener): void;
+    /**
+     * Event delegation: listens on `element` and fires `handler` only when
+     * the event target (or an ancestor up to `element`) matches `selector`.
+     *
+     * Uses `Element.closest()` — no IE polyfill needed.
+     */
+    delegate(element: Element, eventName: string, selector: string, handler: (e: Event, matchedTarget: Element) => void): Destroyable;
+    /**
+     * Calls `fn` when the DOM is ready.  If it's already ready (interactive
+     * or complete), fires immediately.
+     */
+    onReady(fn: () => void): void;
+    /** Prevents default and stops propagation. */
+    stopEvent(e: Event): void;
+    /** Returns `e.pageX` (or `e.clientX` as fallback). */
+    getPageX(e: MouseEvent): number;
+    /** Returns `e.pageY` (or `e.clientY` as fallback). */
+    getPageY(e: MouseEvent): number;
+    /** Returns `e.relatedTarget`. */
+    getRelatedTarget(e: MouseEvent): Element | null;
+    /** Returns `e.key` (modern key value). */
+    getKeyCode(e: KeyboardEvent): string;
+    /**
+     * Removes all listeners registered via {@link on} and {@link delegate}.
+     */
+    removeAll(): void;
+};
+
+/**
+ * @framesquared/core – GestureRecognizer
+ *
+ * Detects touch/pointer gestures and dispatches synthetic CustomEvents
+ * on the target element.  Uses PointerEvent exclusively (no IE).
+ *
+ * Recognized gestures: tap, doubletap, longpress, swipe, pinch, rotate.
+ */
+declare class GestureRecognizer {
+    private el;
+    private pointers;
+    private longpressTimer;
+    private lastTapTime;
+    private destroyed;
+    private initialPinchDistance;
+    private initialPinchAngle;
+    private handleDown;
+    private handleMove;
+    private handleUp;
+    private handleCancel;
+    constructor(element: Element);
+    destroy(): void;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    private onPointerCancel;
+    private startLongpress;
+    private clearLongpress;
+    private fireSwipe;
+    private recordTwoPointerBaseline;
+    private handleTwoPointerMove;
+}
+
+/**
+ * @framesquared/core – KeyMap
+ *
+ * Maps key combinations to handlers.  Supports modifier keys
+ * (Ctrl, Alt, Shift, Meta) with exact matching.
+ *
+ * ```ts
+ * const km = new KeyMap({
+ *   target: myElement,
+ *   bindings: [
+ *     { key: 'Ctrl+S', handler: onSave, preventDefault: true },
+ *     { key: 'Escape', handler: onClose },
+ *   ],
+ * });
+ * ```
+ */
+interface KeyBinding {
+    /** Key combo string, e.g. `"Ctrl+Shift+S"`, `"Enter"`, `"Alt+F4"`. */
+    key: string;
+    /** Handler called when the combo matches. */
+    handler: Function;
+    /** Optional `this` scope for the handler. */
+    scope?: object;
+    /** If true, `e.preventDefault()` is called when the combo matches. */
+    preventDefault?: boolean;
+}
+interface KeyMapConfig {
+    target: Element;
+    bindings: KeyBinding[];
+}
+declare class KeyMap {
+    private target;
+    private parsedBindings;
+    private enabled;
+    private handleKeyDown;
+    constructor(config: KeyMapConfig);
+    private onKeyDown;
+    enable(): void;
+    disable(): void;
+    addBinding(binding: KeyBinding): void;
+    removeBinding(binding: KeyBinding): void;
+    destroy(): void;
+}
+
+/**
+ * @framesquared/core – AriaManager
+ *
+ * Manages ARIA attributes across the framework.  Provides helpers
+ * for setting roles, labels, descriptions, live regions, and
+ * screen reader announcements.
+ */
+declare const AriaManager: {
+    setRole(element: Element, role: string): void;
+    setLabel(element: Element, label: string): void;
+    setLabelledBy(element: Element, id: string): void;
+    setDescription(element: Element, description: string): void;
+    setLive(element: Element, mode: "polite" | "assertive" | "off"): void;
+    announce(message: string, priority?: "polite" | "assertive"): void;
+    /** Generate a unique ID for ARIA linking. */
+    generateId(prefix?: string): string;
+};
+
+/**
+ * @framesquared/core – FocusManager
+ *
+ * Manages focus trapping for modal dialogs, focus save/restore,
+ * and roving tabindex patterns.
+ */
+declare const FocusManager: {
+    /**
+     * Trap focus within a container.  Tab/Shift+Tab cycle among
+     * focusable elements inside the container.
+     */
+    trapFocus(container: HTMLElement): void;
+    /** Release the focus trap. */
+    releaseFocus(): void;
+    isTrapped(): boolean;
+    /** Save the currently focused element for later restoration. */
+    saveFocus(): void;
+    /** Restore focus to the previously saved element. */
+    restoreFocus(): void;
+    /** Reset all state (for tests). */
+    reset(): void;
+};
+
+/**
+ * @framesquared/core – Locale
+ *
+ * Manages translations, number/date formatting (via Intl APIs),
+ * plural rules, RTL direction, and locale-aware collation.
+ */
+interface NumberFormatOptions {
+    currency?: string;
+}
+interface LocaleConfig {
+    language: string;
+    rtl?: boolean;
+    messages: Record<string, string>;
+    dateFormat?: string;
+    timeFormat?: string;
+    numberFormat?: NumberFormatOptions;
+    firstDayOfWeek?: number;
+    pluralRules?: (count: number) => string;
+}
+declare class Locale {
+    private _language;
+    private _rtl;
+    private _messages;
+    private _numberFormat;
+    private _firstDayOfWeek;
+    private _pluralRules;
+    private _collator;
+    private _numberFormatter;
+    private _dateFormatter;
+    private _timeFormatter;
+    private _currencyFormatter;
+    constructor(config: LocaleConfig);
+    getLanguage(): string;
+    isRtl(): boolean;
+    getDirection(): 'ltr' | 'rtl';
+    getFirstDayOfWeek(): number;
+    t(key: string, params?: Record<string, unknown>): string;
+    /**
+     * Translate with plural support.  Appends the plural category
+     * to the key (e.g., 'items.one', 'items.other').
+     */
+    tp(key: string, count: number, params?: Record<string, unknown>): string;
+    getPlural(count: number): string;
+    formatNumber(value: number): string;
+    formatCurrency(value: number): string;
+    formatDate(date: Date): string;
+    formatTime(date: Date): string;
+    compare(a: string, b: string): number;
+}
+
+/**
+ * @framesquared/core – LocaleManager
+ *
+ * Singleton that manages registered locales.  setLocale() applies
+ * dir and lang attributes to document.documentElement and fires
+ * 'localechange'.
+ */
+
+declare const LocaleManager: {
+    register(locale: Locale): void;
+    setLocale(language: string): void;
+    getLocale(): Locale | null;
+    t(key: string, params?: Record<string, unknown>): string;
+    getDirection(): "ltr" | "rtl";
+    on(event: string, fn: Function): void;
+    off(event: string, fn: Function): void;
+    reset(): void;
+};
+
+/**
+ * @framesquared/core – en-US locale bundle
+ */
+
+declare const enUS: Locale;
+
+/**
+ * @framesquared/core – es-ES locale bundle
+ */
+
+declare const esES: Locale;
+
+/**
+ * @framesquared/core – ar-SA locale bundle
+ */
+
+declare const arSA: Locale;
+
+/**
+ * @framesquared/core – Sanitizer
+ *
+ * HTML sanitization utility for safe innerHTML usage.
+ * Uses a whitelist approach — only known-safe tags and attributes pass through.
+ * No dependencies on DOMPurify; uses the browser's own DOMParser.
+ *
+ * @example
+ * ```typescript
+ * import { Sanitizer } from '@framesquared/core';
+ *
+ * const clean = Sanitizer.sanitize('<p onclick="alert(1)">Hello <b>world</b></p>');
+ * // Returns: '<p>Hello <b>world</b></p>'
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare const Sanitizer: {
+    /**
+     * Sanitize an HTML string by removing dangerous tags and attributes.
+     * Uses a whitelist approach — only known-safe elements pass through.
+     *
+     * @param html - Raw HTML string
+     * @returns Sanitized HTML string safe for innerHTML
+     */
+    sanitize(html: string): string;
+    /**
+     * Escape HTML special characters for safe text insertion.
+     *
+     * @param text - Raw text
+     * @returns Escaped string safe for HTML context
+     */
+    escapeHtml(text: string): string;
+    /**
+     * Check if an HTML string contains potentially dangerous content.
+     *
+     * @param html - HTML string to check
+     * @returns true if the HTML appears safe
+     */
+    isSafe(html: string): boolean;
+};
+
+/**
+ * @framesquared/core
+ * Class system, events, and utilities
+ */
+declare const VERSION = "0.0.1";
+
+export { AriaManager, Base, type ClassDefinition, ClassManager, type ConfigMeta, Configurator, type Destroyable, DestroyableUtil, EventBus, EventDomain, EventManager, type EventMap, ExtEvent, Factoryable, FocusManager, GestureRecognizer, Hookable, Identifiable, IdentityMap, Inheritable, type KeyBinding, KeyMap, type KeyMapConfig, type ListenerConfig, type ListenerOptions, Locale, type LocaleConfig, LocaleManager, type NumberFormatOptions, Observable, Pluggable, Plugin, Sanitizer, type TypedObservable, VERSION, alias, apply, applyIf, arSA, bind, camelCase, capitalize, chunk, clean, clone, compose, config, contains, createBarrier, createBuffered, createDelayed, createSequence, createThrottled, defer, define, difference, ellipsis, emptyFn, enUS, entries, equals, esES, escapeHtml, escapeRegex, findBy, flatten, flattenObject, format, freeze, from, fromEntries, generateId, getNestedValue, groupBy, htmlDecode, htmlEncode, identity, include, interceptAfter, interceptBefore, intersection, interval, isArray, isBoolean, isDefined, isEmpty, isFunction, isIterable, isNumber, isObject, isPrimitive, isString, kebabCase, keys, leftPad, mapKeys, mapValues, max, mean, memoize, merge, min, mixin, namespace, negate, now, observable, omit, once, override, partition, pascalCase, pick, pipe, pluck, range, remove, repeat, setNestedValue, sortBy, splitWords, sum, toggle, trim, uncapitalize, unescapeHtml, unflattenObject, unique, values };