titan_bastion 1.0.2

Flutter widgets for Titan state management. Vestige, Beacon, and auto-tracking reactive UI with Pillar architecture.

Titan Bastion

The Bastion — where Titan's power meets the screen

Vestige, Beacon, and auto-tracking reactive UI — powered by the Pillar architecture.

---

Quick Start

flutter pub add titan_bastion

Or see the latest version on pub.dev.

1. Define a Pillar

import 'package:titan_bastion/titan_bastion.dart';

class CounterPillar extends Pillar {
  late final count = core(0);
  late final doubled = derived(() => count.value * 2);

  void increment() => strike(() => count.value++);
}

2. Provide via Beacon

void main() => runApp(
  Beacon(
    pillars: [CounterPillar.new],
    child: const MyApp(),
  ),
);

3. Consume via Vestige

Vestige<CounterPillar>(
  builder: (context, counter) => Text('${counter.count.value}'),
)

Auto-tracking. Only rebuilds when read Cores change. No selectors needed.

---

Widgets

Widget	Description
Vestige<P>	Auto-tracking consumer — rebuilds only when read Cores change
Beacon	Scoped Pillar provider — creates, initializes, and auto-disposes
Confluence2/3/4	Multi-Pillar consumer widget
Lens	In-app debug panel (moved to titan_colossus)
Spark	Hooks-style widget — useCore, useEffect, auto-managed lifecycle

Vestige — Auto-Tracking Consumer

// Reads count.value → rebuilds only when count changes
Vestige<CounterPillar>(
  builder: (context, c) => Text('${c.count.value}'),
)

// Reads doubled.value → rebuilds only when doubled changes
Vestige<CounterPillar>(
  builder: (context, c) => Text('${c.doubled.value}'),
)

Beacon — Scoped Provider

// Single Pillar
Beacon(
  pillars: [CounterPillar.new],
  child: const CounterScreen(),
)

// Multiple Pillars
Beacon(
  pillars: [
    CounterPillar.new,
    AuthPillar.new,
    CartPillar.new,
  ],
  child: const MyApp(),
)

// Feature-scoped (auto-disposes when widget unmounts)
Navigator.push(context, MaterialPageRoute(
  builder: (_) => Beacon(
    pillars: [CheckoutPillar.new],
    child: const CheckoutScreen(),
  ),
));

Confluence — Multi-Pillar Consumer

Confluence2<AuthPillar, CartPillar>(
  builder: (context, auth, cart) => Text(
    '${auth.user.value?.name}: ${cart.itemCount.value} items',
  ),
)

Typed variants: Confluence2, Confluence3, Confluence4. Same auto-tracking as Vestige.

Lens — Debug Overlay

Note: Lens has moved to titan_colossus. Import from package:titan_colossus/titan_colossus.dart.

import 'package:titan_colossus/titan_colossus.dart';

Lens(
  enabled: kDebugMode,
  child: MaterialApp(home: MyApp()),
)

Shows real-time Pillar registrations, Herald events, Vigil errors, and Chronicle logs. Toggle with Lens.show(), Lens.hide(), Lens.toggle().

Spark — Hooks-Style Widget

Eliminate StatefulWidget boilerplate with hooks. No createState, no dispose, no ceremony.

class CounterWidget extends Spark {
  @override
  Widget ignite(BuildContext context) {
    final count = useCore(0);
    final controller = useTextController();

    useEffect(() {
      print('Count changed: ${count.value}');
      return null;
    }, [count.value]);

    return Column(children: [
      TextField(controller: controller),
      Text('Count: ${count.value}'),
      ElevatedButton(
        onPressed: () => count.value++,
        child: Text('Increment'),
      ),
    ]);
  }
}

Available hooks: useCore, useDerived, useEffect, useMemo, useRef, useStream, useTextController, useAnimationController, useFocusNode, useScrollController, useTabController, usePageController, usePillar.

All controllers auto-dispose. All reactive state auto-tracks and rebuilds. Reads .value during ignite() → auto-tracked via TitanEffect, just like Vestige.

Shade Integration: When titan_colossus is active, useTextController(fieldId: 'my_field') automatically creates recording-aware controllers (ShadeTextController) that capture text changes during Shade recording sessions. The fieldId enables accurate text replay via Phantom. See the titan_colossus README for details.

Context Extension

// Access Pillar from context
final counter = context.pillar<CounterPillar>();
counter.increment();

---

Lifecycle

Beacon handles the full lifecycle:

1. Creates Pillar instances via factory functions
2. Initializes — calls onInit() for setup, watchers, subscriptions
3. Provides — makes Pillars available to descendants
4. Disposes — calls onDispose() and cleans up all Cores when widget unmounts

---

Complete Example

import 'package:flutter/material.dart';
import 'package:titan_bastion/titan_bastion.dart';

class CounterPillar extends Pillar {
  late final count = core(0);
  late final doubled = derived(() => count.value * 2);
  void increment() => strike(() => count.value++);
}

void main() => runApp(
  Beacon(
    pillars: [CounterPillar.new],
    child: MaterialApp(
      home: Scaffold(
        body: Center(
          child: Vestige<CounterPillar>(
            builder: (context, c) => Column(
              mainAxisSize: MainAxisSize.min,
              children: [
                Text('Count: ${c.count.value}', style: const TextStyle(fontSize: 48)),
                Text('Doubled: ${c.doubled.value}'),
              ],
            ),
          ),
        ),
        floatingActionButton: Builder(builder: (context) {
          final c = context.pillar<CounterPillar>();
          return FloatingActionButton(
            onPressed: c.increment,
            child: const Icon(Icons.add),
          );
        }),
      ),
    ),
  ),
);

---

Packages

Package	Description
titan	Core reactive engine — pure Dart
titan_bastion	Flutter widgets (this package)
titan_atlas	Routing & navigation (Atlas)

Documentation

Guide	Link
Introduction	01-introduction.md
Getting Started	02-getting-started.md
Core Concepts	03-core-concepts.md
Pillars	04-stores.md
Flutter Integration	05-flutter-integration.md
Oracle & Observation	06-middleware.md
Testing	07-testing.md
Advanced Patterns	08-advanced-patterns.md
API Reference	09-api-reference.md
Migration Guide	10-migration-guide.md
Architecture	11-architecture.md
Atlas Routing	12-atlas-routing.md
Chronicles of Titan	Story-driven tutorial
Chapter IX: The Scroll Inscribes	Form management with Scroll
Chapter X: The Codex Opens	Pagination with Codex
Chapter XI: The Quarry Yields	Data fetching with Quarry
Chapter XII: The Confluence Converges	Multi-Pillar consumer
Chapter XIII: The Lens Reveals	Debug overlay
Chapter XVIII: The Conduit Flows	Core-level middleware
Chapter XIX: The Prism Reveals	Fine-grained state projections
Chapter XX: The Nexus Connects	Reactive collections
Chapter XXI: The Spark Ignites	Hooks-style widgets

License

MIT — Ikolvi