apprun 3.36.0 → 3.37.0

package/plan/plan-apprun-bugfixes.md

@@ -1,207 +0,0 @@
-# AppRun.ts Bug Fixes Implementation Plan
-
-## 🎉 PHASE 1 COMPLETE: All Critical Bugs Fixed!
-
-**Status**: All 4 critical Phase 1 bugs have been successfully resolved and committed.
-
-**Commits**: `072d033`, `fc6469f`, router fix, `93e0371`
-
-**Impact**: 
-- ✅ TypeScript declarations now match implementation perfectly
-- ✅ Version consistency established across all files  
-- ✅ Router initialization logic corrected (critical routing bug fixed)
-- ✅ React 18+ integration improved with proper validation
-
-## Overview
-This plan addresses the critical bugs and issues identified in the AppRun framework, focusing on the main `apprun.ts` file and related dependencies. The fixes are prioritized by severity and impact.
-
-## ✅ Completed Fixes
-
-### 1. TypeScript Declaration File Mismatches - **COMPLETED** 
-- [x] **CRITICAL**: Fix `IApp.use_react` signature mismatch
-  - d.ts: `use_react(React, ReactDOM)` 
-  - Implementation: `use_react(createRoot)` - Fixed parameter signature!
-- [x] Fix missing `once` method in `IApp` interface implementation
-- [x] Fix missing `query` method in `IApp` interface (marked obsolete but still exists)
-- [x] Fix missing `version` property in IApp interface implementation
-- [x] Fix missing `mounted` callback in `AppStartOptions<T>` interface
-- [x] Fix `Component.render` method signature mismatch - Removed from d.ts
-- [x] Fix `AppStartOptions` missing `mounted` callback parameter
-- [x] Sync VNode type definition between d.ts and types.ts
-- **Git Commit**: `072d033` - All TypeScript declaration mismatches resolved
-
-### 2. Version Synchronization - **COMPLETED**
-- [x] Fix version mismatch between `apprun.ts` (3.35.0) and `app.ts` (3.3.11)
-- [x] Establish single source of truth for version management
-- [x] Update version constants to match across all files
-- **Implementation**: Created `/src/version.ts` utility with `APPRUN_VERSION` constant
-- **Git Commit**: Ready for commit
-
-## High Priority Fixes (Critical Bugs)
-
-### 2. Version Synchronization - **COMPLETED**
-- [x] Fix version mismatch between `apprun.ts` (3.35.0) and `app.ts` (3.3.11)
-- [x] Establish single source of truth for version management
-- [x] Update version constants to match across all files
-- **Implementation**: Created `/src/version.ts` utility with `APPRUN_VERSION` constant
-- **Git Commit**: Ready for commit
-
-### 3. Router Logic Correction - **COMPLETED**
-- [x] Fix inverted router initialization logic in `apprun.ts` lines 134-137
-  - Problem: `init_load && route()` should be `!init_load && route()`
-  - When `apprun-no-init` attribute is present, routing should be DISABLED
-  - Current logic routes when disabled and doesn't route when enabled (inverted!)
-  - **Fixed**: Changed logic to `!init_load && route()` for correct behavior
-- [x] Correct `init_load` boolean logic to properly respect no-init flags
-- [x] Test router behavior with and without init flags
-
-### 4. React 18+ Integration Fix
-- [X] Fix missing `ReactDOM` parameter in `use_react` method (matches d.ts issue above)
-- [X] Ensure React 18+ createRoot functionality works correctly
-- [X] Add proper parameter validation for React integration
-
-## Medium Priority Fixes (Type Safety & Reliability)
-
-### 5. Additional TypeScript Declaration Mismatches
-
-### 6. Type Safety Improvements - **COMPLETED**
-- [x] Add null checks before type assertions in event handlers
-- [x] Improve generic type constraints for window object assignments  
-- [x] Add proper TypeScript types for global assignments
-- [x] Enhanced React integration parameter validation
-- [x] Better error handling in event system
-- [x] Safer DOM element access with proper validation
-- **Implementation**: Enhanced type safety across multiple files
-- **Git Commit**: Ready for commit
-
-### 7. Memory Leak Prevention
-- [ ] Implement cleanup mechanism for DOM event listeners
-- [ ] Add component cache cleanup strategy
-- [ ] Create proper unsubscribe methods for router events
-
-### 8. Global State Management
-- [ ] Preserve existing React global before overwriting
-- [ ] Add safety checks for global object modifications
-- [ ] Implement proper global state restoration
-
-## Low Priority Fixes (Performance & Edge Cases)
-
-### 9. Document Ready State Handling
-- [ ] Add check for document.readyState === 'complete'
-- [ ] Handle late script loading scenarios
-- [ ] Ensure initialization occurs regardless of load timing
-
-### 10. Router Edge Cases
-- [ ] Add validation for malformed URLs
-- [ ] Implement error boundaries for routing failures
-- [ ] Handle empty/undefined route scenarios
-
-### 11. Performance Optimizations
-- [ ] Cache expensive DOM queries (`app.find('#')`, `app.find('#/')`)
-- [ ] Optimize repeated lookups in router logic
-- [ ] Reduce unnecessary event listener registrations
-
-## Testing & Validation
-
-### 12. Test Coverage - **COMPLETED**
-- [x] Create unit tests for fixed router logic
-- [x] Add integration tests for React compatibility  
-- [x] Test memory leak scenarios with repeated component mounting
-- [x] Validate version consistency across builds
-- [x] Test TypeScript declaration file accuracy
-- **Implementation**: Created comprehensive test suites covering all critical bug fixes
-  - `router-fix.spec.ts`: Tests router initialization logic and no-init attribute behavior
-  - `react-compatibility.spec.ts`: Tests React 18+ integration and parameter validation
-  - `memory-leak.spec.ts`: Tests component lifecycle and event system memory management
-  - `version-consistency.spec.ts`: Tests version synchronization and single source of truth
-  - `typescript-declarations.spec.ts`: Tests TypeScript interface compliance and accuracy
-- **Git Commit**: Ready for commit
-
-### 13. Regression Testing
-- [ ] Test existing functionality after each fix
-- [ ] Verify backward compatibility
-- [ ] Check for any breaking changes in public API
-
-## Implementation Strategy
-
-### Phase 1: Critical Fixes
-1. TypeScript declaration file mismatches
-2. Version synchronization
-3. Router logic correction
-4. React integration fix
-
-### Phase 2: Safety & Reliability
-5. Additional TypeScript declaration mismatches
-6. Type safety improvements
-7. Memory leak prevention
-8. Global state management
-
-### Phase 3: Polish & Optimization
-9. Document ready state handling
-10. Router edge cases
-11. Performance optimizations
-12. Testing & validation
-
-## Files to be Modified
-
-### Primary Files
-- [ ] `/src/apprun.ts` - Main entry point fixes
-- [ ] `/src/app.ts` - Version constant update
-- [ ] `/src/router.ts` - Edge case handling
-- [ ] `/apprun.d.ts` - TypeScript declaration fixes
-
-### Secondary Files
-- [ ] `/src/types.ts` - Type safety improvements
-- [ ] `/src/component.ts` - Memory management fixes
-
-### New Files
-- [ ] Create version management utility
-- [ ] Add cleanup utility functions
-- [ ] Create router validation helpers
-
-## Risk Assessment
-
-### Low Risk
-- Version synchronization
-- Type safety improvements
-- Performance optimizations
-- TypeScript declaration fixes
-
-### Medium Risk
-- Router logic changes
-- Memory management modifications
-- Global state handling
-
-### High Risk
-- React integration changes (potential breaking changes)
-- Event listener cleanup (could affect existing apps)
-
-## Rollback Strategy
-- [ ] Create backup of current working version
-- [ ] Implement feature flags for major changes
-- [ ] Maintain backward compatibility where possible
-- [ ] Document any breaking changes clearly
-
-## Success Criteria
-- [ ] All identified bugs fixed without introducing new issues
-- [ ] No breaking changes to public API
-- [ ] Memory usage remains stable or improves
-- [ ] Router functionality works correctly in all scenarios
-- [ ] React integration works with all supported versions
-- [ ] All tests pass including new regression tests
-
-## Timeline Estimate
-- Phase 1 (Critical): 2-3 days
-- Phase 2 (Safety): 2-3 days  
-- Phase 3 (Polish): 1-2 days
-- Testing & Validation: 1-2 days
-- **Total Estimated Time: 6-10 days**
-
-## Dependencies
-- No external dependencies for core fixes
-- May need to update build scripts for version management
-- Testing framework should be available for validation
-
----
-
-**Note**: This plan should be reviewed and approved before implementation begins. Each checkbox represents a discrete task that can be implemented and tested independently.

package/src/types/apprun.d.ts

@@ -1,56 +0,0 @@
-declare type VNode = {
-  tag: string;
-  props?: Record<string, any>;
-  children?: Array<VNode | string | number>;
-} | string | number;
-
-declare type VDOM = VNode | VNode[];
-
-declare type View<T = any> = (state: T) => VDOM | void;
-declare type Action<T = any> = (state: T, ...p: any[]) => T | void | Promise<T>;
-declare type ActionDef<T = any> = [Action<T>, object?];
-declare type Update<T = any> = { [name: string]: Action<T> | ActionDef<T> | Array<Action<T> | ActionDef<T>> };
-
-declare interface IApp {
-  start<T>(element?: Element | string | null, model?: T, view?: View<T>, update?: Update<T>, options?: AppStartOptions): Component<T>;
-  on(name: string, fn: (...args: any[]) => void, options?: any): void;
-  run(name: string, ...args: any[]): void;
-  createElement(tag: string | Function, props?: any, ...children: any[]): VNode;
-  render(element: Element, node: VNode): void;
-}
-
-declare interface Component<T = any> {
-  readonly state: T;
-  setState(state: T, options?: any): void;
-  mount(element?: Element | string | null, options?: any): Component<T>;
-  start(element?: Element | string | null, options?: any): Component<T>;
-  run(name: string, ...args: any[]): void;
-  rendered?: (state: T) => void;
-  view?: View<T>;
-  update?: Update<T>;
-  element?: Element;
-}
-
-declare interface CustomElementOptions {
-  render?: boolean;
-  shadow?: boolean;
-  history?: boolean | { prev: string; next: string };
-  global_event?: boolean;
-  route?: string;
-}
-
-declare interface AppStartOptions extends CustomElementOptions {
-  render?: boolean;
-  history?: boolean | { prev: string; next: string };
-  global_event?: boolean;
-  route?: string;
-}
-
-declare interface Route {
-  (url: string): void;
-  push(url: string, notify?: boolean): void;
-}
-
-declare const app: IApp;
-declare function on<T = any>(name?: string, options?: any): (target: any, key: string) => void;
-declare function Component<T = any>(options?: any): (constructor: Function) => void;