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

11 KiB Raw Blame History