159 lines
11 KiB
Markdown
159 lines
11 KiB
Markdown
# Neon Framework
|
|
|
|
## Overview
|
|
Neon Framework is a Dart-based UI framework for building mobile apps (Android & iOS). It is a standalone SDK — no Flutter dependency. Built iteratively in phases following real SDK development patterns.
|
|
|
|
## Current State
|
|
- **Phase 0 (Vision)**: Locked. See `neon_framework/PHASE_0_VISION.md`
|
|
- **Phase 1 (Core Runtime)**: Complete.
|
|
- **Phase 2 (Widget System)**: Complete.
|
|
- **Phase 3 (Rendering Layer)**: Complete.
|
|
- **Phase 4 (State Management)**: Complete.
|
|
- **Phase 5 (Platform Layer)**: Complete.
|
|
- **Phase 6 (Tooling)**: Complete.
|
|
- **Phase 7 (Storage & Networking)**: Complete.
|
|
- **Phase 8 (Plugins & Extensibility)**: Complete.
|
|
|
|
## Project Architecture
|
|
|
|
### Directory Structure
|
|
```
|
|
neon_framework/
|
|
bin/
|
|
neon.dart # CLI entry point (executable)
|
|
lib/
|
|
neon.dart # Barrel export
|
|
src/
|
|
core/
|
|
neon_app.dart # NeonApp.run() entry point
|
|
lifecycle.dart # Lifecycle manager (onInit, onPause, onResume, onDispose, onHotReload)
|
|
error_handler.dart # Environment-aware error handling
|
|
environment.dart # NeonConfig, NeonBuildFlavor, NeonFeatureFlags
|
|
widgets/
|
|
widget.dart # NeonWidget, StatelessWidget, StatefulWidget, NeonState
|
|
build_context.dart # NeonBuildContext with inherited data
|
|
primitives.dart # NeonColor, NeonTextStyle, NeonEdgeInsets, enums
|
|
text.dart # Text widget
|
|
button.dart # Button widget with tap handling
|
|
container.dart # Container widget (box model)
|
|
layout.dart # Column, Row, Stack layout widgets
|
|
widget_tree.dart # NeonWidgetTree, NeonElement tree builder
|
|
rendering/
|
|
constraints.dart # NeonSize, NeonOffset, NeonRect, NeonConstraints
|
|
render_object.dart # NeonRenderObject base class
|
|
canvas.dart # NeonCanvas, NeonPaintCommand, NeonDeviceInfo
|
|
render_widgets.dart # RenderText, RenderContainer, RenderColumn, RenderRow, RenderStack
|
|
render_pipeline.dart # NeonRenderPipeline (Layout → Paint → Composite)
|
|
animation.dart # Animation foundation (values, curves, spring, duration)
|
|
state/
|
|
signal.dart # NeonSignal, NeonComputed, NeonEffect (reactive primitives)
|
|
async_value.dart # NeonAsyncValue (loading/success/error/cached)
|
|
state_widget.dart # SignalMixin, NeonSignalProvider (widget integration)
|
|
platform/
|
|
platform_channel.dart # NeonPlatformChannel, NeonPlatformDispatcher (message passing)
|
|
platform_bridge.dart # NeonPlatformBridge singleton (manages all platform services)
|
|
native_renderer.dart # NeonNativeRenderer (sends paint commands to native canvas)
|
|
platform_info.dart # NeonPlatformInfo (device info, OS, safe areas)
|
|
file_system.dart # NeonFileSystem (sandboxed file I/O)
|
|
platform_lifecycle.dart # NeonPlatformLifecycle (bridges native lifecycle to Neon)
|
|
tooling/
|
|
cli.dart # NeonCli runner, NeonLogger
|
|
command_create.dart # neon create — project scaffolding
|
|
command_run.dart # neon run — compile and launch with hot reload
|
|
command_build.dart # neon build — release build for Android/iOS
|
|
command_doctor.dart # neon doctor — environment checks
|
|
command_clean.dart # neon clean — wipe build artifacts
|
|
project_template.dart # NeonProjectTemplate (app/minimal scaffolding)
|
|
neon_project.dart # NeonProject loader (pubspec + neon.yaml)
|
|
hot_reload.dart # HotReloadEngine, HotReloadSession
|
|
data/
|
|
kv_store.dart # NeonKeyValueStore, NeonKVBackend, NeonMemoryKVBackend
|
|
database.dart # NeonDatabase, NeonTableSchema, NeonColumn, NeonMigration
|
|
http_client.dart # NeonHttpClient, NeonHttpRequest/Response, mock backend
|
|
web_socket.dart # NeonWebSocket, NeonWebSocketMessage, mock backend
|
|
cache_policy.dart # NeonCachePolicy, NeonCacheStore, NeonCacheEntry
|
|
plugins/
|
|
plugin.dart # NeonPlugin, NeonDartPlugin, NeonNativePlugin, NeonPluginManifest
|
|
plugin_registry.dart # NeonPluginRegistry, NeonPluginHook, NeonPluginException
|
|
example_plugins.dart # NeonLoggerPlugin, NeonDeviceInfoPlugin
|
|
example/
|
|
main.dart # Example app demonstrating full pipeline
|
|
test/
|
|
core_test.dart # Unit tests (307 tests)
|
|
pubspec.yaml
|
|
analysis_options.yaml
|
|
PHASE_0_VISION.md
|
|
PHASE_6_TOOLING.md
|
|
PHASE_7_DATA.md
|
|
```
|
|
|
|
### Key Decisions
|
|
- **App Entry**: `NeonApp.run(MyApp())` — clean, namespaced
|
|
- **Lifecycle**: Full lifecycle events via observer pattern (onInit, onPause, onResume, onDispose, onHotReload)
|
|
- **Error Handling**: Configurable per environment (crash in dev, recover+log in staging/prod)
|
|
- **Environment**: Supports Dev/Staging/Prod configs, build flavors, runtime feature flags
|
|
- **Widget Model**: StatelessWidget / StatefulWidget split with NeonState
|
|
- **Build Method**: `NeonWidget build(NeonBuildContext context)` returns widget tree nodes
|
|
- **Immutability**: Hybrid — widget descriptions immutable, state objects mutable with controlled rebuilds
|
|
- **Core Widgets**: Text, Button, Container, Column, Row, Stack
|
|
- **Widget Tree**: NeonWidgetTree builds NeonElement tree from root widget
|
|
- **BuildContext**: Supports inherited data via provide/findAncestor pattern
|
|
- **Layout System**: Constraints-based (Flutter-like) — parent passes constraints down, child returns size
|
|
- **Render Pipeline**: Layout → Paint → Composite with display list
|
|
- **Coordinate System**: Logical pixels + device pixel ratio support
|
|
- **Render Objects**: RenderText, RenderContainer, RenderColumn, RenderRow, RenderStack
|
|
- **Canvas**: NeonCanvas emits paint commands (drawRect, drawText, drawCircle, drawLine, etc.)
|
|
- **Animation Foundation**: NeonAnimationValue, curves (linear, easeIn, easeOut, easeInOut), spring simulation
|
|
- **State Management**: Custom reactive signals (NeonSignal, NeonComputed, NeonEffect)
|
|
- **Async State**: NeonAsyncValue with loading/success/error/cached states and pattern matching (when/maybeWhen)
|
|
- **Signal Integration**: SignalMixin for NeonState auto-rebuilds, NeonSignalProvider for context-based signal sharing
|
|
- **Dependency Tracking**: Automatic tracking via _NeonDependencyTracker stack; effects and computeds re-track on each run
|
|
- **Platform Bridge**: Method channels + FFI hybrid; singleton NeonPlatformBridge manages all platform services
|
|
- **Platform Channels**: Typed bidirectional message passing (NeonPlatformChannel) with mock dispatcher for testing
|
|
- **Native Renderer**: NeonNativeRenderer serializes paint commands and submits frames with performance tracking
|
|
- **Platform Info**: NeonPlatformInfo provides device info, OS version, safe area insets, dark mode detection
|
|
- **File System**: NeonFileSystem with sandboxed storage locations (appDocuments, appCache, appSupport, temp)
|
|
- **Platform Lifecycle**: NeonPlatformLifecycle bridges native lifecycle events (Android Activity / iOS AppDelegate) to Neon's lifecycle manager
|
|
- **CLI**: `neon` command with create/run/build/doctor/clean subcommands, powered by `args` package
|
|
- **Project Scaffolding**: App and minimal templates with neon.yaml project config
|
|
- **Hot Reload**: Three-tier strategy (UI-only, state-preserving, full fallback) with file watcher and debounce
|
|
- **Key-Value Store**: Typed KV store with backend abstraction and prefix-based namespace isolation
|
|
- **SQLite Database**: Schema-based table definitions, migrations, and query builder with mock backend
|
|
- **HTTP Client**: REST client with interceptors, base URL resolution, mock backend for testing
|
|
- **WebSocket**: Real-time client with auto-reconnect, JSON messaging, and event hooks
|
|
- **Cache Policy**: Five strategies (cache-first, network-first, cache-only, network-only, stale-while-revalidate) with TTL-based cache store
|
|
- **Plugin Model**: Dual-mode (Dart-only + Native) with NeonPlugin base class, manifest-driven registration
|
|
- **Plugin Registry**: Singleton with dependency resolution, capability conflict detection, SDK version validation
|
|
- **Plugin Hooks**: Named hook system for loose coupling between plugins and app code
|
|
- **Plugin Distribution**: Git-based primary, manual import, registry deferred
|
|
- **Philosophy**: Custom hybrid (Flutter tree + Compose functions + SwiftUI diffing)
|
|
|
|
### Phase Plan
|
|
| Phase | Name | Status |
|
|
|-------|------|--------|
|
|
| 0 | Vision & Constraints | Locked |
|
|
| 1 | Core Runtime | Complete |
|
|
| 2 | Widget System | Complete |
|
|
| 3 | Rendering Layer | Complete |
|
|
| 4 | State Management | Complete |
|
|
| 5 | Platform Layer | Complete |
|
|
| 6 | Tooling | Complete |
|
|
| 7 | Storage & Networking | Complete |
|
|
| 8 | Plugins & Extensibility | Complete |
|
|
| 9 | Optimization & Stability | Pending |
|
|
|
|
## User Preferences
|
|
- Building iteratively with `.md` prompt files per phase
|
|
- VS Code support for building apps with Neon SDK
|
|
- Final output: downloadable Neon SDK (Dart package)
|
|
- Target platforms: Android & iOS only
|
|
|
|
## Recent Changes
|
|
- 2026-02-09: Phase 0 vision locked, Phase 1 core runtime implemented and tested
|
|
- 2026-02-09: Phase 2 widget system implemented — StatelessWidget/StatefulWidget, core widgets, widget tree builder, 45 tests passing
|
|
- 2026-02-09: Phase 3 rendering layer implemented — constraints-based layout, render pipeline, canvas with paint commands, animation foundation, 72 tests passing
|
|
- 2026-02-09: Phase 4 state management implemented — NeonSignal, NeonComputed, NeonEffect, NeonAsyncValue, SignalMixin, NeonSignalProvider, 102 tests passing
|
|
- 2026-02-09: Phase 5 platform integration implemented — NeonPlatformChannel, NeonPlatformBridge, NeonNativeRenderer, NeonPlatformInfo, NeonFileSystem, NeonPlatformLifecycle, 131 tests passing
|
|
- 2026-02-09: Phase 6 tooling implemented — CLI (create/run/build/doctor/clean), project templates, hot reload engine, 169 tests passing
|
|
- 2026-02-09: Phase 7 storage & networking implemented — KV store, SQLite database, HTTP client, WebSocket, cache policies, 250 tests passing
|
|
- 2026-02-09: Phase 8 plugins & extensibility implemented — Plugin model (Dart-only + Native), plugin registry with dependency/capability validation, hooks, logger & device-info example plugins, 307 tests passing
|