@smilodon/core 1.0.0

package/dist/types/src/utils/dom-pool.d.ts

@@ -0,0 +1,79 @@
+/**
+ * DOM Node Pool with LRU eviction and aggressive cleanup.
+ * Reuses nodes to minimize GC pressure and layout thrashing.
+ *
+ * Features:
+ * - LRU eviction when pool exceeds maxSize
+ * - Style reset to avoid style pollution
+ * - Event listener cleanup
+ * - Performance telemetry integration
+ */
+export interface DOMPoolOptions {
+    /** Maximum pool size (default: renderedNodes + 32) */
+    maxSize?: number;
+    /** Factory function to create new nodes */
+    factory: () => HTMLElement;
+    /** Reset function called before reuse */
+    reset?: (node: HTMLElement) => void;
+    /** Enable performance telemetry */
+    telemetry?: boolean;
+}
+export declare class DOMPool {
+    private pool;
+    private factory;
+    private reset;
+    private maxSize;
+    private telemetry;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(options: DOMPoolOptions);
+    /**
+     * Acquire a node from pool or create new one
+     * Complexity: O(n) for LRU scan, amortized O(1) for small pools
+     */
+    acquire(): HTMLElement;
+    /**
+     * Release node back to pool
+     * Complexity: O(n) to find node
+     */
+    release(node: HTMLElement): void;
+    /**
+     * Evict least recently used node
+     * Complexity: O(n)
+     */
+    private evictLRU;
+    /**
+     * Default reset: clear content, remove inline styles, remove attributes
+     */
+    private defaultReset;
+    /**
+     * Deep cleanup before eviction/destruction
+     */
+    private deepCleanup;
+    /**
+     * Clear entire pool
+     */
+    clear(): void;
+    /**
+     * Adjust max pool size dynamically
+     */
+    setMaxSize(size: number): void;
+    /**
+     * Get pool statistics
+     */
+    getStats(): {
+        total: number;
+        available: number;
+        inUse: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+        evictions: number;
+        hitRate: number;
+    };
+    /**
+     * Reset telemetry counters
+     */
+    resetTelemetry(): void;
+}

package/dist/types/src/utils/fenwick-tree.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Fenwick Tree (Binary Indexed Tree) for O(log n) prefix sum queries and updates.
+ * Used for cumulative height calculations in variable-height virtualization.
+ *
+ * Space: O(n)
+ * Time: O(log n) for both query and update
+ *
+ * @see https://en.wikipedia.org/wiki/Fenwick_tree
+ */
+export declare class FenwickTree {
+    private tree;
+    private size;
+    constructor(size: number);
+    /**
+     * Add delta to index i (0-indexed input)
+     * Complexity: O(log n)
+     */
+    add(index: number, delta: number): void;
+    /**
+     * Get prefix sum from 0 to index (inclusive, 0-indexed input)
+     * Complexity: O(log n)
+     */
+    sum(index: number): number;
+    /**
+     * Get sum in range [left, right] (inclusive, 0-indexed)
+     * Complexity: O(log n)
+     */
+    rangeSum(left: number, right: number): number;
+    /**
+     * Update value at index to newValue (handles delta internally)
+     * Requires tracking current values externally or use add() directly
+     * Complexity: O(log n)
+     */
+    update(index: number, oldValue: number, newValue: number): void;
+    /**
+     * Binary search to find the smallest index where sum(index) >= target
+     * Useful for finding scroll position -> item index mapping
+     * Complexity: O(log² n) or O(log n) with optimization
+     *
+     * @returns index (0-indexed) or -1 if not found
+     */
+    lowerBound(target: number): number;
+    /**
+     * Reset all values to 0
+     * Complexity: O(n)
+     */
+    reset(): void;
+    /**
+     * Resize the tree (useful for dynamic item lists)
+     * Complexity: O(n)
+     */
+    resize(newSize: number): void;
+    /**
+     * Get current size
+     */
+    getSize(): number;
+    /**
+     * Export state for serialization (e.g., to SharedArrayBuffer)
+     */
+    exportState(): {
+        size: number;
+        tree: number[];
+    };
+    /**
+     * Import state from serialization
+     */
+    static fromState(state: {
+        size: number;
+        tree: number[];
+    }): FenwickTree;
+}

package/dist/types/src/utils/security.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Security utilities for CSP-compliant environments.
+ * All utilities are opt-in and do not run by default.
+ */
+/**
+ * HTML Sanitizer interface - developers must provide their own implementation
+ * (e.g., DOMPurify) or use the no-op default.
+ */
+export interface HTMLSanitizer {
+    sanitize(html: string): string;
+}
+/**
+ * Set a custom HTML sanitizer (e.g., DOMPurify).
+ *
+ * @example
+ * import DOMPurify from 'dompurify';
+ * setHTMLSanitizer({
+ *   sanitize: (html) => DOMPurify.sanitize(html)
+ * });
+ */
+export declare function setHTMLSanitizer(sanitizer: HTMLSanitizer): void;
+/**
+ * Reset to the default no-op sanitizer.
+ * Mainly for testing purposes.
+ */
+export declare function resetHTMLSanitizer(): void;
+/**
+ * Get the current HTML sanitizer.
+ */
+export declare function getHTMLSanitizer(): HTMLSanitizer;
+/**
+ * Sanitize HTML using the registered sanitizer.
+ * WARNING: Default is no-op! Set a real sanitizer for untrusted content.
+ *
+ * @param html - HTML string to sanitize
+ * @returns Sanitized HTML string
+ */
+export declare function sanitizeHTML(html: string): string;
+/**
+ * Create a text node (CSP-safe alternative to innerHTML for text content).
+ *
+ * @param text - Text content
+ * @returns Text node
+ */
+export declare function createTextNode(text: string): Text;
+/**
+ * Set text content safely (CSP-compliant).
+ *
+ * @param element - Target element
+ * @param text - Text content
+ */
+export declare function setTextContent(element: Element, text: string): void;
+/**
+ * Create an element with attributes (CSP-safe).
+ * No inline styles or event handlers.
+ *
+ * @param tagName - HTML tag name
+ * @param attributes - Element attributes (excluding style and on* handlers)
+ * @param textContent - Optional text content
+ * @returns Created element
+ */
+export declare function createElement(tagName: string, attributes?: Record<string, string>, textContent?: string): HTMLElement;
+/**
+ * Set CSS custom properties (CSP-safe way to style elements).
+ *
+ * @param element - Target element
+ * @param properties - CSS custom properties (e.g., { '--color': 'red' })
+ */
+export declare function setCSSProperties(element: HTMLElement, properties: Record<string, string>): void;
+/**
+ * Feature detection utilities for CSP-restricted environments.
+ */
+export declare const CSPFeatures: {
+    /**
+     * Check if inline scripts are allowed (CSP: script-src 'unsafe-inline').
+     */
+    hasInlineScripts(): boolean;
+    /**
+     * Check if eval is allowed (CSP: script-src 'unsafe-eval').
+     */
+    hasEval(): boolean;
+    /**
+     * Check if SharedArrayBuffer is available.
+     * Required for some Worker features, blocked without COOP/COEP headers.
+     */
+    hasSharedArrayBuffer(): boolean;
+    /**
+     * Check if Web Workers are available and functional.
+     */
+    hasWorkers(): boolean;
+    /**
+     * Check if we're in a sandboxed iframe.
+     */
+    isSandboxed(): boolean;
+    /**
+     * Check CSP policy via meta tag or SecurityPolicyViolationEvent.
+     */
+    getCSPDirectives(): string[];
+};
+/**
+ * Runtime environment checks for degraded features.
+ */
+export interface EnvironmentCapabilities {
+    canUseWorkers: boolean;
+    canUseSharedArrayBuffer: boolean;
+    canUseInlineScripts: boolean;
+    canUseEval: boolean;
+    isSandboxed: boolean;
+    cspDirectives: string[];
+}
+/**
+ * Detect environment capabilities once at initialization.
+ */
+export declare function detectEnvironment(): EnvironmentCapabilities;
+/**
+ * Validation for untrusted HTML in templates.
+ * Logs warning if no sanitizer is configured.
+ */
+export declare function validateTemplate(html: string, source: string): string;
+/**
+ * Check if a string looks like it might contain executable code.
+ */
+export declare function containsSuspiciousPatterns(str: string): boolean;
+/**
+ * Escape HTML entities for text content.
+ */
+export declare function escapeHTML(text: string): string;
+/**
+ * Escape attribute values.
+ */
+export declare function escapeAttribute(attr: string): string;

package/dist/types/src/utils/telemetry.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Performance telemetry module for tracking frame timing and performance metrics.
+ * Uses PerformanceObserver for precise measurements.
+ *
+ * Tracks:
+ * - Frame time (should be < 16.67ms for 60fps)
+ * - Main thread work per frame (target < 8ms, ideal 4-6ms)
+ * - Long tasks (> 50ms blocks)
+ * - Memory usage (if available)
+ */
+export interface FrameMetrics {
+    frameTime: number;
+    fps: number;
+    longTasks: number;
+    droppedFrames: number;
+}
+export interface PerformanceMetrics {
+    frames: FrameMetrics;
+    mainThreadWork: number;
+    longTaskCount: number;
+    memory?: {
+        usedJSHeapSize: number;
+        totalJSHeapSize: number;
+        jsHeapSizeLimit: number;
+    };
+}
+export declare class PerformanceTelemetry {
+    private frameTimes;
+    private longTasks;
+    private lastFrameTime;
+    private rafId;
+    private measuring;
+    private observer;
+    private workTimes;
+    constructor();
+    /**
+     * Setup PerformanceObserver for long tasks
+     */
+    private setupObserver;
+    /**
+     * Start measuring frame performance
+     */
+    start(): void;
+    /**
+     * Stop measuring
+     */
+    stop(): void;
+    /**
+     * Measure frame timing via requestAnimationFrame
+     */
+    private measureFrame;
+    /**
+     * Mark start of work for custom measurement
+     */
+    markStart(label: string): void;
+    /**
+     * Mark end of work and measure duration
+     */
+    markEnd(label: string): number;
+    /**
+     * Get current metrics snapshot
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Check if performance is acceptable
+     */
+    isPerformanceGood(): boolean;
+    /**
+     * Get detailed report as string
+     */
+    getReport(): string;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+export declare function getTelemetry(): PerformanceTelemetry;
+/**
+ * Helper to measure async function execution
+ */
+export declare function measureAsync<T>(label: string, fn: () => Promise<T>): Promise<{
+    result: T;
+    duration: number;
+}>;
+/**
+ * Helper to measure sync function execution
+ */
+export declare function measureSync<T>(label: string, fn: () => T): {
+    result: T;
+    duration: number;
+};

package/dist/types/src/utils/virtualizer.d.ts

@@ -0,0 +1,53 @@
+type ItemGetter = (index: number) => unknown;
+export interface VirtualizerOptions {
+    estimatedItemHeight: number;
+    buffer: number;
+    maxPoolExtra?: number;
+    measurementThreshold?: number;
+    enableTelemetry?: boolean;
+}
+export declare class Virtualizer {
+    private container;
+    private itemsLength;
+    private options;
+    measuredHeights: Map<number, number>;
+    averageHeight: number;
+    private pool;
+    private itemGetter;
+    private fenwick?;
+    private activeNodes;
+    constructor(container: HTMLElement, itemsLength: number, itemGetter: ItemGetter, options: VirtualizerOptions);
+    computeWindow(scrollTop: number, viewportHeight: number): {
+        startIndex: number;
+        endIndex: number;
+        windowSize: number;
+    };
+    cumulativeOffset(index: number): number;
+    acquireNode(index: number): HTMLElement;
+    releaseNode(index: number): void;
+    releaseExcess(activeIndices: Set<number>): void;
+    render(startIndex: number, endIndex: number, updateNode: (node: HTMLElement, item: unknown, index: number) => void): void;
+    measureOnAppear(node: HTMLElement, index: number): void;
+    /**
+     * Get pool statistics (if telemetry enabled)
+     */
+    getPoolStats(): {
+        total: number;
+        available: number;
+        inUse: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+        evictions: number;
+        hitRate: number;
+    };
+    /**
+     * Update items length and resize Fenwick tree if needed
+     */
+    setItemsLength(newLength: number): void;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+export {};

package/dist/types/src/utils/worker-manager.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Web Worker protocol types for off-main-thread processing.
+ * Supports heavy transforms, fuzzy search, and data processing.
+ */
+export interface WorkerRequest {
+    id: string;
+    type: 'transform' | 'search' | 'filter' | 'sort';
+    payload: unknown;
+}
+export interface WorkerResponse<T = unknown> {
+    id: string;
+    success: boolean;
+    data?: T;
+    error?: string;
+    duration?: number;
+}
+export interface TransformRequest {
+    items: unknown[];
+    transformer: string;
+}
+export interface SearchRequest {
+    items: unknown[];
+    query: string;
+    fuzzy?: boolean;
+    maxResults?: number;
+}
+export interface FilterRequest {
+    items: unknown[];
+    predicate: string;
+}
+export interface SortRequest {
+    items: unknown[];
+    comparator: string;
+}
+/**
+ * Worker manager for handling off-main-thread processing.
+ * Automatically falls back if workers not available or blocked by COOP/COEP.
+ */
+export declare class WorkerManager {
+    private worker;
+    private pending;
+    private supportsWorkers;
+    private supportsSharedArrayBuffer;
+    private nextId;
+    constructor();
+    /**
+     * Detect browser capabilities
+     */
+    private detectFeatures;
+    /**
+     * Initialize worker (inline blob URL for simplicity)
+     */
+    private initWorker;
+    /**
+     * Generate worker code as string
+     */
+    private generateWorkerCode;
+    /**
+     * Handle worker message
+     */
+    private handleMessage;
+    /**
+     * Handle worker error
+     */
+    private handleError;
+    /**
+     * Execute operation (worker or fallback)
+     */
+    execute<T = unknown>(type: WorkerRequest['type'], payload: unknown, timeout?: number): Promise<T>;
+    /**
+     * Fallback to main thread execution
+     */
+    private executeFallback;
+    /**
+     * Transform items with custom function
+     */
+    transform<T, R>(items: T[], transformer: (item: T, index: number) => R): Promise<R[]>;
+    /**
+     * Search items with optional fuzzy matching
+     */
+    search<T>(items: T[], query: string, fuzzy?: boolean): Promise<{
+        item: T;
+        index: number;
+    }[]>;
+    /**
+     * Filter items with predicate
+     */
+    filter<T>(items: T[], predicate: (item: T, index: number) => boolean): Promise<T[]>;
+    /**
+     * Sort items with comparator
+     */
+    sort<T>(items: T[], comparator: (a: T, b: T) => number): Promise<T[]>;
+    /**
+     * Check if workers are supported
+     */
+    get hasWorkerSupport(): boolean;
+    /**
+     * Check if SharedArrayBuffer is supported
+     */
+    get hasSharedArrayBuffer(): boolean;
+    /**
+     * Terminate worker
+     */
+    destroy(): void;
+}
+export declare function getWorkerManager(): WorkerManager;

package/dist/types/tests/csp.spec.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CSP (Content Security Policy) compliance test suite.
+ * Verifies the library works in CSP-restricted environments.
+ */
+export {};

package/dist/types/tests/interaction.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tests/setup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Test setup - runs before all tests
+ */
+import '../src/components/native-select';
+import '../src/components/enhanced-select';
+import '../src/components/select-option';

package/dist/types/tests/shadow-dom.spec.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shadow DOM security and isolation tests.
+ * Tests closed shadow roots, nested embeddings, and isolation boundaries.
+ */
+export {};

package/dist/types/tests/smoke.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tests/stress.spec.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Stress tests for extreme scale performance validation.
+ * Tests 1M+ items, heavy transforms, worker offloading.
+ */
+export {};

package/dist/types/tests/virtualizer.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@smilodon/core",
+  "version": "1.0.0",
+  "description": "High-performance native select component with extreme-scale virtualization",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly --outDir dist/types",
+    "dev": "rollup -c --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "size": "gzip -c dist/index.js | wc -c"
+  },
+  "keywords": [
+    "select",
+    "dropdown",
+    "virtualization",
+    "web-components",
+    "custom-element",
+    "performance"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "rollup": "^4.9.0",
+    "typescript": "^5.6.2",
+    "vitest": "^1.6.0",
+    "jsdom": "^24.0.0"
+  },
+  "sideEffects": [
+    "./src/components/enhanced-select.ts",
+    "./src/components/native-select.ts",
+    "./dist/**/*.js"
+  ]
+}