@saolabs/client 1.0.0

package/src/core/contracts/ElementInterface.ts

@@ -0,0 +1,140 @@
+import type { OneObjectType } from "../types/utils";
+import type { ViewControllerInterface } from "./ViewControllerInterface";
+import type { ReactiveInterface } from "./ReactiveInterface";
+
+// ─── Element Interfaces ──────────────────────────────────────────
+
+/** Base for any renderable node in the tree */
+export interface OneNodeInterface {
+    oneType: OneObjectType;
+    parent: HtmlInterface | null;
+    render(): void;
+    destroy(): void;
+    isOneElement: boolean;
+    setParentElement(parent: HtmlInterface | null): void;
+    [key: string]: any;
+
+}
+
+/** Native HTML element wrapper */
+export interface HtmlInterface extends OneNodeInterface {
+    element: HTMLElement;
+    domChildren: Node[];
+    [key: string]: any;
+}
+
+/** Text node wrapper */
+export interface TextInterface extends OneNodeInterface {
+    element: Text;
+    text: string;
+
+
+    domChildren: Node[];
+    update(newText: string): void;
+}
+
+export interface OutputInterface extends OneNodeInterface {
+    ctx: ViewControllerInterface;
+    parent: HtmlInterface | null;
+    stateKeys: string[];
+    openTag: Comment;
+    closeTag: Comment;
+    domChildren: Node[];
+    [key: string]: any;
+}
+
+export interface YieldInterface extends OneNodeInterface {
+    ctx: ViewControllerInterface;
+    parent: HtmlInterface | null;
+    name: string;
+    contentFactory: () => OneChildrenFactoryOutput;
+    setContentFactory(factory: () => OneChildrenFactoryOutput): void;
+    openTag: Comment;
+    closeTag: Comment;
+    domChildren: Node[];
+    [key: string]: any;
+}
+
+/** Fragment — renders multiple root nodes into a parent without a wrapping tag */
+export interface FragmentInterface extends OneNodeInterface {
+    nodes: Node[];
+    domChildren: Node[];
+    [key: string]: any;
+
+}
+/** Wrapper — renders multiple root nodes into a parent without a wrapping tag */
+export interface WrapperInterface extends OneNodeInterface {
+    nodes: Node[];
+    domChildren: Node[];
+    [key: string]: any;
+}
+
+// ─── Element Config Types ────────────────────────────────────────
+
+export type OneElementConfig = {
+    attrs?: {
+        [key: string]: {
+            type: 'value' | 'binding';
+            value?: any;
+            stateKeys?: string[];
+            factory?: () => any;
+        }
+    },
+    props?: {
+        [key: string]: {
+            type: 'value' | 'binding';
+            value?: any;
+            stateKeys?: string[];
+            factory?: () => any;
+        }
+    },
+    events?: {
+        [key: string]: OneElementEventHandler;
+    },
+    classes?: {
+        [className: string]: {
+            type: 'static' | 'binding';
+            value?: boolean;
+            stateKeys?: string[];
+            factory?: () => boolean;
+        }
+    } | Array<{
+        type: 'static' | 'binding';
+        value?: string;
+        stateKeys?: string[];
+        factory?: () => boolean;
+    }>,
+    styles?: {
+        [prop: string]: {
+            type: 'value' | 'binding';
+            value?: string;
+            stateKeys?: string[];
+            factory?: () => string;
+        }
+    },
+    [key: string]: any;
+}
+
+export type HtmlElementConfig = OneElementConfig & {
+    ctx: ViewControllerInterface;
+    parentElement?: HtmlInterface | null;
+    parent?: HtmlInterface | null;
+}
+
+// ─── Event Handler ──────────────────────────────────────────────
+
+export type OneElementEventHandler = Array<{
+    handler: string | ((event: Event) => any);
+    params?: (any | ((event: Event) => any[]))[];
+} | ((event: Event) => any)>;
+
+// ─── Children Types ─────────────────────────────────────────────
+
+/** All possible rendered child node types */
+export type OneElementChildren = Array<HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface | HTMLElement | SVGElement | DocumentFragment | Text | Comment>;
+
+/** What a children factory can return (before mounting) */
+export type OneChildrenFactoryOutput = Array<HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface | string | number | HTMLElement | SVGElement | DocumentFragment | Text | Comment>;
+
+/** Factory function that produces children given parent element */
+export type OneChildrenFactory = (parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;

package/src/core/contracts/EventServiceInterface.ts

@@ -0,0 +1,47 @@
+// ─── Event Service Interface ─────────────────────────────────────
+
+export type EventCallback = (...args: any[]) => void;
+
+export interface EventServiceInterface {
+    /**
+     * Subscribe to events. Returns unsubscribe function.
+     *
+     * Supports:
+     *   - Single event:       on('click', fn)
+     *   - Multiple events:    on(['click', 'hover'], fn)
+     *   - Space-separated:    on('click hover', fn)
+     *   - Object syntax:      on({ click: fn1, hover: fn2 })
+     */
+    on(event: string | string[] | Record<string, EventCallback>, callback?: EventCallback | boolean, once?: boolean): () => void;
+
+    /** Subscribe once — auto-unsubscribe after first call */
+    once(event: string | string[] | Record<string, EventCallback>, callback?: EventCallback): () => void;
+
+    /**
+     * Unsubscribe from events.
+     *
+     * - off('save')          — remove all listeners for 'save'
+     * - off('save', fn)      — remove specific listener
+     * - off(['save', 'update'])
+     * - off({ save: fn1 })
+     */
+    off(event: string | string[] | Record<string, EventCallback>, callback?: EventCallback): void;
+
+    /** Emit event with arguments */
+    emit(event: string, ...args: any[]): void;
+
+    /** Remove all listeners */
+    clear(): void;
+
+    /** Listener count for a specific event */
+    listenerCount(event: string): number;
+
+    /** Check if event has listeners */
+    hasListeners(event: string): boolean;
+
+    /** Get all registered event names */
+    eventNames(): string[];
+
+    /** Destroy — alias for clear */
+    destroy(): void;
+}

package/src/core/contracts/HelperInterface.ts

@@ -0,0 +1,256 @@
+// ─── Collection Proxy Interface ─────────────────────────────────
+
+import { ApplicationInterface } from "./ApplicationInterface";
+
+export interface CollectionProxyInterface {
+    all(): any[];
+    toArray(): any[];
+    count(): number;
+    isEmpty(): boolean;
+    isNotEmpty(): boolean;
+    first(cb?: (item: any) => boolean): any;
+    last(cb?: (item: any) => boolean): any;
+    get(index: number, defaultValue?: any): any;
+    map(cb: (item: any, i: number) => any): CollectionProxyInterface;
+    filter(cb?: (item: any, i: number) => boolean): CollectionProxyInterface;
+    reject(cb: (item: any) => boolean): CollectionProxyInterface;
+    reduce(cb: (carry: any, item: any) => any, initial?: any): any;
+    each(cb: (item: any, i: number) => void): CollectionProxyInterface;
+    pluck(key: string): CollectionProxyInterface;
+    where(key: string, value: any): CollectionProxyInterface;
+    whereIn(key: string, values: any[]): CollectionProxyInterface;
+    whereNotIn(key: string, values: any[]): CollectionProxyInterface;
+    sortBy(key: string | ((a: any) => any)): CollectionProxyInterface;
+    sortByDesc(key: string | ((a: any) => any)): CollectionProxyInterface;
+    reverse(): CollectionProxyInterface;
+    unique(key?: string): CollectionProxyInterface;
+    flatten(depth?: number): CollectionProxyInterface;
+    chunk(size: number): CollectionProxyInterface;
+    take(count: number): CollectionProxyInterface;
+    skip(count: number): CollectionProxyInterface;
+    sum(key?: string | ((item: any) => number)): number;
+    avg(key?: string): number;
+    min(key?: string): any;
+    max(key?: string): any;
+    contains(key: any, value?: any): boolean;
+    groupBy(key: string | ((item: any) => string)): Record<string, any[]>;
+    keyBy(key: string | ((item: any) => string)): Record<string, any>;
+    join(glue: string, finalGlue?: string): string;
+    push(...items: any[]): CollectionProxyInterface;
+    prepend(...items: any[]): CollectionProxyInterface;
+    pop(): any;
+    shift(): any;
+    merge(other: any[]): CollectionProxyInterface;
+    values(): CollectionProxyInterface;
+    keys(): CollectionProxyInterface;
+    tap(cb: (collection: CollectionProxyInterface) => void): CollectionProxyInterface;
+    pipe<T>(cb: (collection: CollectionProxyInterface) => T): T;
+    toJSON(): any[];
+    toString(): string;
+}
+
+// ─── Helper Interface ───────────────────────────────────────────
+
+export interface HelperInterface {
+    [key: string]: any;
+
+     // ─── App / Service Container ─────────────────────────────────
+    app<T>(): T;
+    app<T>(key: string): T;
+    app<T>(key: string, value: any): ApplicationInterface;
+    make<T>(name: string, defaultValue?: T): T | undefined;
+
+    // ─── Execution ──────────────────────────────────────────────
+    execute<T>(fn: () => T): T;
+    exec(fn: Function, ...args: any[]): any;
+
+    // ─── Type Checks ────────────────────────────────────────────
+    isset(...values: any[]): boolean;
+    empty(value: any): boolean;
+    is_null(value: any): boolean;
+    is_array(value: any): boolean;
+    is_string(value: any): boolean;
+    is_numeric(value: any): boolean;
+    is_object(value: any): boolean;
+    is_bool(value: any): boolean;
+    is_int(value: any): boolean;
+    is_float(value: any): boolean;
+
+    // ─── Count / Length ─────────────────────────────────────────
+    count(value: any): number;
+    sizeof(value: any): number;
+
+    // ─── String Functions ───────────────────────────────────────
+    strlen(str: any): number;
+    substr(str: any, start: number, length?: number): string;
+    mb_substr(str: any, start: number, length?: number): string;
+    trim(str: any, chars?: string): string;
+    ltrim(str: any, chars?: string): string;
+    rtrim(str: any, chars?: string): string;
+    strtolower(str: any): string;
+    strtoupper(str: any): string;
+    ucfirst(str: any): string;
+    lcfirst(str: any): string;
+    ucwords(str: any, delimiters?: string): string;
+    str_replace(search: string | string[], replace: string | string[], subject: string): string;
+    str_ireplace(search: string | string[], replace: string | string[], subject: string): string;
+    explode(delimiter: string, str: any, limit?: number): string[];
+    implode(glue: string, pieces?: any[]): string;
+    str_repeat(str: any, times: number): string;
+    str_pad(input: any, length: number, padString?: string, padType?: number): string;
+    str_contains(haystack: any, needle: string): boolean;
+    str_starts_with(haystack: any, needle: string): boolean;
+    str_ends_with(haystack: any, needle: string): boolean;
+    str_word_count(str: any, format?: number): number | string[];
+    str_split(str: any, length?: number): string[];
+    substr_count(haystack: any, needle: string, offset?: number, length?: number): number;
+    substr_replace(str: any, replacement: string, start: number, length?: number): string;
+    nl2br(str: any, isXhtml?: boolean): string;
+    wordwrap(str: any, width?: number, breakStr?: string, cutLongWords?: boolean): string;
+    chunk_split(body: any, chunklen?: number, end?: string): string;
+    sprintf(format: string, ...args: any[]): string;
+    mb_strtolower(str: any): string;
+    mb_strtoupper(str: any): string;
+    mb_strlen(str: any): number;
+    strpos(haystack: any, needle: string, offset?: number): number | false;
+    strrpos(haystack: any, needle: string, offset?: number): number | false;
+    stripos(haystack: any, needle: string, offset?: number): number | false;
+    str_getcsv(str: any, separator?: string, enclosure?: string, escape?: string): string[];
+
+    // ─── HTML / Encoding ────────────────────────────────────────
+    htmlspecialchars(str: any, flags?: number, encoding?: string, doubleEncode?: boolean): string;
+    htmlspecialchars_decode(str: any): string;
+    escapeHtml(str: any): string;
+    escString(value: any): string;
+    strip_tags(str: any, allowedTags?: string): string;
+    addslashes(str: any): string;
+    stripslashes(str: any): string;
+    urlencode(str: any): string;
+    urldecode(str: any): string;
+    rawurlencode(str: any): string;
+    rawurldecode(str: any): string;
+    base64_encode(str: any): string;
+    base64_decode(str: any): string;
+    md5(str: any): string;
+    sha1(str: any): string;
+    crc32(str: any): number;
+
+    // ─── Array Functions ────────────────────────────────────────
+    array_push(arr: any[], ...items: any[]): number;
+    array_pop(arr: any[]): any;
+    array_shift(arr: any[]): any;
+    array_unshift(arr: any[], ...items: any[]): number;
+    array_merge(...arrays: any[]): any[] | Record<string, any>;
+    array_keys(arr: any): string[] | number[];
+    array_values(arr: any): any[];
+    array_reverse(arr: any[], preserveKeys?: boolean): any[];
+    array_unique(arr: any[]): any[];
+    array_slice(arr: any[], offset: number, length?: number, preserveKeys?: boolean): any[];
+    array_splice(arr: any[], offset: number, length?: number, ...replacement: any[]): any[];
+    array_map(callback: ((item: any, key?: any) => any) | null, arr: any, ...arrays: any[]): any[];
+    array_filter(arr: any, callback?: (value: any, key?: any) => boolean): any[];
+    array_reduce(arr: any[], callback: (carry: any, item: any) => any, initial?: any): any;
+    array_find(arr: any[], callback: (value: any, key?: any) => boolean): any;
+    array_find_key(arr: any[], callback: (value: any, key?: any) => boolean): number | null;
+    array_column(arr: any[], columnKey: string, indexKey?: string): any[] | Record<string, any>;
+    array_combine(keys: any[], values: any[]): Record<string, any>;
+    array_chunk(arr: any[], size: number, preserveKeys?: boolean): any[][];
+    array_pad(arr: any[], size: number, value: any): any[];
+    array_flip(arr: any): Record<string, any>;
+    array_sum(arr: any[]): number;
+    array_product(arr: any[]): number;
+    array_count_values(arr: any[]): Record<string, number>;
+    array_fill(startIndex: number, num: number, value: any): any[];
+    array_fill_keys(keys: any[], value: any): Record<string, any>;
+    array_intersect(arr: any[], ...arrays: any[][]): any[];
+    array_diff(arr: any[], ...arrays: any[][]): any[];
+    array_intersect_key(obj: Record<string, any>, ...objects: Record<string, any>[]): Record<string, any>;
+    array_diff_key(obj: Record<string, any>, ...objects: Record<string, any>[]): Record<string, any>;
+    array_search(needle: any, haystack: any[], strict?: boolean): number | string | false;
+    in_array(needle: any, haystack: any[], strict?: boolean): boolean;
+    array_key_exists(key: string | number, arr: any): boolean;
+    sort(arr: any[]): boolean;
+    rsort(arr: any[]): boolean;
+    ksort(obj: Record<string, any>): Record<string, any>;
+    krsort(obj: Record<string, any>): Record<string, any>;
+    usort(arr: any[], compareFunc: (a: any, b: any) => number): boolean;
+    uasort(arr: any[], compareFunc: (a: any, b: any) => number): boolean;
+    uksort(obj: Record<string, any>, compareFunc: (a: string, b: string) => number): Record<string, any>;
+    range(start: number | string, end: number | string, step?: number): (number | string)[];
+    compact(...names: string[]): Record<string, any>;
+    head(arr: any[]): any;
+    last(arr: any[]): any;
+
+    // ─── Math Functions ─────────────────────────────────────────
+    min(...values: any[]): any;
+    max(...values: any[]): any;
+    abs(n: number): number;
+    ceil(n: number): number;
+    floor(n: number): number;
+    round(n: number, precision?: number): number;
+    sqrt(n: number): number;
+    pow(base: number, exp: number): number;
+    log(n: number, base?: number): number;
+    log10(n: number): number;
+    exp(n: number): number;
+    fmod(x: number, y: number): number;
+    intdiv(a: number, b: number): number;
+    pi(): number;
+    rand(min?: number, max?: number): number;
+    mt_rand(min?: number, max?: number): number;
+    array_rand(arr: any[], num?: number): number | number[];
+
+    // ─── JSON ───────────────────────────────────────────────────
+    json_encode(value: any, options?: number): string;
+    json_decode(json: any, assoc?: boolean): any;
+
+    // ─── Number Formatting ──────────────────────────────────────
+    number_format(number: number | string, decimals?: number, decimalSeparator?: string, thousandsSeparator?: string): string;
+    formatNumber(num: number, options?: { decimals?: number; thousandsSeparator?: string; decimalSeparator?: string; prefix?: string; suffix?: string }): string;
+    formatCurrency(amount: number, currency?: string, locale?: string): string;
+
+    // ─── Date / Time ────────────────────────────────────────────
+    now(): Date;
+    today(): Date;
+    date(format: string, timestamp?: number): string;
+    time(): number;
+    strtotime(dateStr: string, baseTimestamp?: number): number | false;
+    mktime(hour?: number, minute?: number, second?: number, month?: number, day?: number, year?: number): number;
+    microtime(asFloat?: boolean): string | number;
+    formatDate(date: Date | string | number, format?: string): string;
+    diffInDays(date1: Date | string, date2?: Date | string): number;
+    diffInHours(date1: Date | string, date2?: Date | string): number;
+    diffInMinutes(date1: Date | string, date2?: Date | string): number;
+    diffInSeconds(date1: Date | string, date2?: Date | string): number;
+    addDays(date: Date | string, days: number): Date;
+    subDays(date: Date | string, days: number): Date;
+    addHours(date: Date | string, hours: number): Date;
+    subHours(date: Date | string, hours: number): Date;
+    addMinutes(date: Date | string, minutes: number): Date;
+    subMinutes(date: Date | string, minutes: number): Date;
+
+    // ─── Type Conversion ────────────────────────────────────────
+    intval(value: any, base?: number): number;
+    floatval(value: any): number;
+    strval(value: any): string;
+    boolval(value: any): boolean;
+    gettype(value: any): string;
+
+    // ─── Misc Helpers ───────────────────────────────────────────
+    slug(str: any, separator?: string): string;
+    truncate(str: any, length?: number, suffix?: string): string;
+    uniqid(prefix?: string, moreEntropy?: boolean): string;
+    collect(items?: any[]): CollectionProxyInterface;
+    dd(...args: any[]): never;
+    dump(...args: any[]): void;
+    var_dump(...args: any[]): void;
+    print_r(value: any, returnOutput?: boolean): string | void;
+    class_exists(name: string): boolean;
+    function_exists(name: string): boolean;
+    url(path?: string): string;
+    asset(path: string): string;
+    deepClone<T>(obj: T): T;
+    data_get(obj: any, path: string, defaultValue?: any): any;
+    data_set(obj: any, path: string, value: any): void;
+    old(key: string, defaultValue?: any): any;
+}

package/src/core/contracts/HttpServiceInterface.ts

@@ -0,0 +1,51 @@
+// ─── HTTP Service Interface ──────────────────────────────────────
+
+export interface HttpRequestConfig extends RequestInit {
+    headers?: Record<string, string>;
+    timeout?: number;
+    [key: string]: any;
+}
+
+export interface HttpResponse<T = any> {
+    status: boolean;
+    statusCode: number;
+    data: T;
+    headers: Headers;
+}
+
+export interface HttpInterceptor {
+    request?: (config: HttpRequestConfig) => HttpRequestConfig | Promise<HttpRequestConfig>;
+    response?: <T = any>(response: HttpResponse<T>) => HttpResponse<T> | Promise<HttpResponse<T>>;
+    error?: (error: Error) => Error | Promise<Error>;
+}
+
+export interface HttpServiceInterface {
+    // ─── Config ─────────────────────────────────────────────────
+    setBaseUrl(url: string): this;
+    setTimeout(ms: number): this;
+    setDefaultHeaders(headers: Record<string, string>): this;
+    setHeader(name: string, value: string): this;
+    removeHeader(name: string): this;
+
+    /** Add interceptor. Returns unregister function. */
+    addInterceptor(interceptor: HttpInterceptor): () => void;
+
+    // ─── Core Request ───────────────────────────────────────────
+    request<T = any>(method: string, url: string, data?: any, options?: HttpRequestConfig): Promise<HttpResponse<T>>;
+
+    // ─── Convenience ────────────────────────────────────────────
+    get<T = any>(url: string, params?: any, options?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    post<T = any>(url: string, data?: any, options?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    put<T = any>(url: string, data?: any, options?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    patch<T = any>(url: string, data?: any, options?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    delete<T = any>(url: string, options?: HttpRequestConfig): Promise<HttpResponse<T>>;
+
+    // ─── Cancellation ───────────────────────────────────────────
+    /** Cancel all pending requests */
+    cancelAll(): void;
+    /** Cancel a specific pending request */
+    cancel(url: string, method?: string): void;
+
+    /** Destroy — cancel all + clear interceptors */
+    destroy(): void;
+}

package/src/core/contracts/LoggerServiceInterface.ts

@@ -0,0 +1,48 @@
+// ─── Logger Service Interface ────────────────────────────────────
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+export interface LoggerConfig {
+    /** Minimum log level to output (default: 'info') */
+    level?: LogLevel;
+    /** Enable/disable console output (default: true) */
+    enabled?: boolean;
+    /** Prefix for all log messages (default: '') */
+    prefix?: string;
+    /** Max history entries (0 = unlimited, default: 500) */
+    maxHistory?: number;
+}
+
+export interface LogEntry {
+    level: LogLevel;
+    timestamp: number;
+    args: any[];
+}
+
+export interface LoggerServiceInterface {
+    // ─── Config ─────────────────────────────────────────────────
+    setConfig(config: Partial<LoggerConfig>): void;
+    getConfig(): Readonly<Required<LoggerConfig>>;
+    enable(): void;
+    disable(): void;
+    setLevel(level: LogLevel): void;
+    setPrefix(prefix: string): void;
+
+    // ─── Log Methods ────────────────────────────────────────────
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+
+    // ─── History ────────────────────────────────────────────────
+    /** Get all stored log entries */
+    getHistory(): readonly LogEntry[];
+    /** Get history filtered by level */
+    getHistoryByLevel(level: LogLevel): LogEntry[];
+    /** Clear log history */
+    clearHistory(): void;
+
+    // ─── Lifecycle ──────────────────────────────────────────────
+    destroy(): void;
+}

package/src/core/contracts/LoopContextInterface.ts

@@ -0,0 +1,15 @@
+// ─── LoopContext Interface ───────────────────────────────────────
+
+export interface LoopContextInterface {
+    index: number;
+    iteration: number;
+    count: number;
+    remaining: number;
+    first: boolean;
+    last: boolean;
+    odd: boolean;
+    even: boolean;
+    depth: number;
+    parent: LoopContextInterface | null;
+    next(): void;
+}

package/src/core/contracts/MarkerInterface.ts

@@ -0,0 +1,77 @@
+
+
+export interface MarkerRegistryRecord {
+    /** Full tag name: 'reactive', 'block', 'foreach', etc. */
+    tag: string;
+    /** Unique ID for this marker (e.g. 'r:m0') */
+    registryID: string;
+    /** Arbitrary metadata */
+    attributes: Record<string, any>;
+}
+
+export type MarkerTagName =
+    | 'view' | 'component' | 'layout' | 'template'
+    | 'block' | 'blockoutlet' | 'reactive' | 'section' | 'fragment'
+    | 'for' | 'forin' | 'foreach' | 'while'
+    | 'if' | 'switch'
+    | 'include' | 'yield' | 'slot'
+    | 'echo' | 'echoescaped'
+    | 'useblock' | 'extend'
+    | 'style' | 'script'
+    | (string & {}); // Allow custom tags
+
+
+// ─── MarkerRegistry Service ─────────────────────────────────────
+
+
+export type MarkerFilter = string | Record<string, any>;
+export interface MarkerRecord {
+    name: string;
+    tagName: string;
+    registryID?: string | null;
+    attributes: Record<string, any>;
+    openTag: Comment;
+    closeTag: Comment;
+    children: Array<Node>;
+    [key: string]: any;
+}
+export interface MarkupAttributes {
+    [key: string]: string;
+}
+
+export interface MarkupQueryOptions {
+    multiple?: boolean;
+    recursive?: boolean;
+}
+
+export interface MarkupQuery {
+    pattern: string;
+    attributes?: MarkupAttributes;
+    options?: MarkupQueryOptions;
+    index?: number;
+}
+
+/**
+ * RegistryTag Query Options
+ */
+export interface RegistryTagQueryOptions {
+    tag?: string;
+    id?: string;
+    attributes?: Record<string, any>;
+    multiple?: boolean;
+}
+
+/**
+ * RegistryTagData
+ */
+export interface RegistryTagData {
+    systemPrefix: string;
+    tag: string;
+    id: string;
+    key: string;
+    attributes?: Record<string, any>;
+    nodes: Array<Node>;
+}
+
+
+export type RegistryIDOrAttributes = string | Record<string, any> | undefined;

package/src/core/contracts/ReactiveInterface.ts

@@ -0,0 +1,45 @@
+import type { OneObjectType } from "../types/utils";
+import type { ViewControllerInterface } from "./ViewControllerInterface";
+import type { HtmlInterface, OneChildrenFactoryOutput, OneElementChildren, OneNodeInterface } from "./ElementInterface";
+
+// ─── Reactive Interface ──────────────────────────────────────────
+
+/** Reactive region bounded by comment markers — re-renders when deps change */
+export interface ReactiveInterface extends OneNodeInterface {
+    oneType: OneObjectType;
+    id: string;
+    type: string;
+    ctx: ViewControllerInterface;
+    stateKeys: string[];
+    parentElement: HtmlInterface | null;
+    parentReactive: ReactiveInterface | null;
+    openTag: Comment;
+    closeTag: Comment;
+    children: OneElementChildren;
+    unsubscribe: () => void;
+    childrenFactory: ReactiveChildrenFactory;
+    setChildrenFactory(factory: ReactiveChildrenFactory): void;
+    setStateKeys(stateKeys: string[]): void;
+    render(): void;
+    destroy(): void;
+    isOneElement: boolean;
+    isOneReactive: boolean;
+}
+
+// ─── Reactive Types ──────────────────────────────────────────────
+
+/** Function called by Reactive to produce DOM content between markers */
+export type ReactiveRenderFn = (ctx: ViewControllerInterface, parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+
+/** Factory function for reactive children rendering */
+export type ReactiveChildrenFactory = (parentReactive: ReactiveInterface, parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+
+/** Reactive configuration */
+export type ReactiveConfig = {
+    type?: string;
+    id?: string;
+    stateKeys?: string[];
+    options?: any;
+    attributes?: Record<string, any>;
+    createdMode?: 'csr' | 'ssr';
+}