neon_mobile_framework/replit.md

Neon Framework

Overview

Neon Framework is a custom Dart-based UI framework for building native mobile apps (Android & iOS) without any Flutter dependency. It is a standalone SDK that owns its own runtime, widget system, rendering pipeline, state management, and platform bridges. The framework communicates with native apps via an HTTP-based bridge — the Dart backend runs a local HTTP server that serves a JSON widget tree, and native apps (Android/iOS) fetch this tree, render native UI components, and send user actions back via POST requests.

The project has completed 8 development phases: Vision → Core Runtime → Widget System → Rendering Layer → State Management → Platform Layer → Tooling (CLI) → Storage & Networking → Plugins & Extensibility.

The main framework code lives in neon_framework/ and a test app lives in neon_framework/my_2nd_test_app/ with both Android (Kotlin) and iOS (Swift) native shells.

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Core Framework (neon_framework/lib/src/)

The framework follows a layered architecture:

1. Core Runtime (core/): NeonApp.run() entry point, lifecycle management (onInit, onPause, onResume, onDispose, onHotReload), environment-aware error handling, and configuration via NeonConfig, NeonBuildFlavor, and NeonFeatureFlags.

2. Widget System (widgets/): Inspired by Flutter's composition model. Includes NeonWidget, StatelessWidget, StatefulWidget, and NeonState. Widgets build a tree (NeonWidgetTree / NeonElement) and serialize to JSON for native rendering. Includes primitives (Text, Button, Container) and layouts (Column, Row, Stack). Material 3 widgets (Switch, Checkbox, Radio, Slider, Chips, Badge, Card, Dialog, BottomSheet, TextField, SearchBar, SearchAnchor, MenuAnchor, MenuBar) are also supported.

3. Rendering Layer (rendering/): Custom layout engine with constraints, render objects, canvas abstractions, and a render pipeline (Layout → Paint → Composite). Includes animation foundations with curves and spring physics.

4. State Management (state/): Reactive primitives — NeonSignal (observable values), NeonComputed (derived values), NeonEffect (side effects), and NeonAsyncValue (loading/success/error/cached states). setState() triggers widget tree rebuilds and re-serialization.

5. Data Layer (storage/, networking/): Key-value store, SQLite database with migrations, HTTP client with interceptors, WebSocket client with auto-reconnect, and a cache policy system (cache-first, network-first, stale-while-revalidate, etc.).

6. Plugin System (plugins/): Dual-mode architecture supporting Dart-only and native plugins. Includes a plugin registry with dependency resolution, capability conflict detection, lifecycle management, and a hook system. Semantic versioning and SDK constraints are enforced.

7. CLI Tooling (bin/neon.dart, tooling/): Commands for create, run, build, doctor, clean. Hot reload engine with file watching, debounce, and three reload tiers (UI-only, state-preserving, full).

Platform Bridge Architecture

This is the most important architectural pattern to understand:

• Dart side runs an HTTP server (typically on localhost:8080)
• GET / returns the full widget tree as JSON
• POST /action receives user interactions (widget ID, index, value) and returns the updated widget tree as JSON
• Native apps (Android MainActivity.kt, iOS ViewController.swift) fetch the JSON tree, recursively render native UI components, and send actions back when users interact
• State updates flow: User taps → native sends POST → Dart finds widget by ID → calls callback → setState() → tree rebuilds → new JSON sent back → native re-renders

Key Design Decisions

• No Flutter: This is intentional. The framework owns its entire stack. Don't add Flutter dependencies.
• JSON-based rendering: Widgets serialize to JSON maps. The native side interprets these maps to create native Android/iOS views. This is the bridge between Dart logic and native UI.
• Widget keys: Interactive widgets must have stable string keys so the native apps can target them for action events. Missing keys was a recurring bug source.
• double.infinity handling: JSON doesn't support infinity values. These must be clamped or replaced before serialization.
• Microtask timing: setState() is async — the action handler must await Future.delayed(Duration.zero) before rebuilding the tree, to let the microtask queue flush.

Test App Structure

my_2nd_test_app/ contains:

• lib/ — Dart app code using the Neon Framework (8 screens: Dashboard, Interaction, Controls, Values, Advanced, Containment, Input, Info & Progress)
• android/ — Gradle-based Android project with MainActivity.kt that renders the JSON widget tree
• NeonApp/ — Xcode project with ViewController.swift that renders the JSON widget tree on iOS

Recent Changes (Phase 10 - Information & Progress Widgets)

• Added 8 new Material 3 widget types: ListTile, LinearProgressIndicator, CircularProgressIndicator, Tooltip, SnackBar, SingleChildScrollView, ListView (with builder/separated variants), CustomScrollView with sliver support (SliverList, SliverAppBar)
• Full JSON serialization, action handling, and HTML/CSS/JS web renderer for all new widgets
• Native Android (Kotlin) and iOS (Swift) rendering support for all new widgets
• New Info & Progress showcase screen demonstrating all new widget types
• Navigation bar expanded to 8 tabs
• Fixed Radio button generic type crash: added selectValue() method to bypass Dart generic type erasure issue with onChanged callback
• Previous phase 9 changes preserved: Card, Dialog, BottomSheet, TextField, SearchBar, MenuAnchor/MenuBar
• Fixed web renderer Button click bug: Container type check was matching before Button check in the JS renderer, preventing buttons (whose type is Container but sourceType is Button) from being clickable. Moved isButton/Button check before Container check. Native renderers (Android/iOS) already handled this via isButton flag.
• Fixed nested AppBar/NavigationBar rendering: When ShowcaseApp is embedded inside AppLauncher, the AppBar and NavigationBar were nested inside Expanded/ShowcaseApp rather than at root level. Added inline rendering for both widget types in renderWidget() so they display correctly at any nesting depth. Also added NavigationBar, TabBar, and AppBar to the interactable widget list in widget_tree.dart for proper action routing.

Flutter-to-Neon Transpiler (tools/transpiler/)

• Purpose: Source-to-source converter that transforms Flutter widget code into Neon-compatible code
• Entry point: tools/transpiler/main.dart — runs before the main app in the workflow
• Input: Place Flutter .dart files in flutter_input/ directory
• Output: Converted files go to lib/neon_compat/ with a barrel export neon_compat.dart
• Widget mapping (tools/transpiler/widget_mapping.dart): Maps ~50 Flutter widgets/types to Neon equivalents
• Key transformations:
  • Flutter imports → package:neon_framework/neon.dart
  • StatelessWidget/StatefulWidget → Neon base classes
  • State<T> → NeonState<T>
  • Widget build(BuildContext) → NeonWidget build(NeonBuildContext)
  • ElevatedButton → FilledButton, TextStyle → NeonTextStyle, EdgeInsets → NeonEdgeInsets, etc.
  • Key? key → String? key
  • Removes Flutter-specific imports, handles Scaffold removal
• Usage: dart run tools/transpiler/main.dart [input_dir] [output_dir]
• Uses: analyzer package for Dart AST parsing to find widget classes

External Dependencies

Dart Packages (from pubspec)

• analyzer — Dart AST parsing for the transpiler
• args — CLI argument parsing
• path — File path manipulation
• watcher — File system watching for hot reload
• test (dev) — Unit testing

Native Platform Dependencies

• Android: Standard Android SDK (API 21+), Kotlin, Gradle. Uses java.net.URL for HTTP communication with the Dart backend. Native widgets include android.widget.Switch, CheckBox, RadioButton, SeekBar, etc.
• iOS: UIKit-based (not SwiftUI). Uses URLSession for HTTP communication. Native widgets include UISwitch, UIButton, UISlider, etc. Xcode project targets iOS simulator (arm64).

No Database or External Services

The framework includes its own storage abstractions (key-value store, SQLite) with in-memory backends for testing. There is no external database dependency like Postgres. The HTTP client and WebSocket client are built-in with mock backends available.