Titan Colossus #

Enterprise-grade performance monitoring for the Titan ecosystem.

Colossus — named after the Colossus of Rhodes, a representation of the Titan Helios — stands watch over your app's performance, seeing every frame, every navigation, every allocation.

Features #

Quick Start #

1. Add dependency #

dev_dependencies:
  titan_colossus: ^1.0.0

2. Initialize via plugin (recommended) #

import 'package:titan_colossus/titan_colossus.dart';

void main() {
  runApp(
    Beacon(
      pillars: [MyPillar.new],
      plugins: [
        if (kDebugMode) ColossusPlugin(
          tremors: [Tremor.fps(), Tremor.leaks()],
          // AI Blueprint Generation — all enabled by default
          enableTableauCapture: true,   // Shade records screen metadata
          autoLearnSessions: true,      // Shade → Scout auto-feed
          autoAtlasIntegration: true,   // Auto-wire Atlas observer & routes
          // AI-Bridge Export — auto-save Blueprint on app shutdown
          blueprintExportDirectory: '.titan',
        ),
      ],
      child: MaterialApp.router(routerConfig: atlas.config),
    ),
  );
}

One line to add, one line to remove. ColossusPlugin handles Colossus.init(), wraps with Lens and ShadeListener, auto-wires Atlas observer, feeds Shade recordings into Scout, and calls Colossus.shutdown() on dispose.

Manual initialization (alternative) #

import 'package:titan_colossus/titan_colossus.dart';

void main() {
  if (kDebugMode) {
    Colossus.init(
      tremors: [
        Tremor.fps(),
        Tremor.leaks(),
        Tremor.pageLoad(),
      ],
    );
  }

  runApp(
    Lens(
      enabled: kDebugMode,
      child: MaterialApp.router(routerConfig: atlas.config),
    ),
  );
}

That's it. Colossus auto-registers its Lens tab and begins monitoring.

The Colossus Lexicon #

Usage #

Pulse — Frame Monitoring #

Pulse automatically tracks every frame via Flutter's addTimingsCallback:

final colossus = Colossus.instance;
print('FPS: ${colossus.pulse.fps}');
print('Jank rate: ${colossus.pulse.jankRate}%');
print('Avg build: ${colossus.pulse.avgBuildTime.inMicroseconds}µs');

Stride — Page Load Timing #

Automatic with Atlas:

final atlas = Atlas(
  passages: [...],
  observers: [ColossusAtlasObserver()],
);

Manual timing:

final sw = Stopwatch()..start();
await loadHeavyData();
sw.stop();
Colossus.instance.stride.record('/data', sw.elapsed);

Vessel — Memory & Leak Detection #

Vessel periodically checks Titan's DI registry for Pillar lifecycle anomalies:

Colossus.init(
  vesselConfig: VesselConfig(
    leakThreshold: Duration(minutes: 3),
    exemptTypes: {'AuthPillar', 'AppPillar'}, // Long-lived, not leaks
  ),
);

Echo — Rebuild Tracking #

Wrap widgets to track their rebuild count:

Echo(
  label: 'QuestList',
  child: QuestListWidget(),
)

View rebuild data in the Lens "Perf" tab or via code:

final rebuilds = Colossus.instance.rebuildsPerWidget;
print(rebuilds); // {QuestList: 42, HeroProfile: 7}

Tremor — Performance Alerts #

Configure alerts that emit Herald events when thresholds are breached:

Colossus.init(
  tremors: [
    Tremor.fps(threshold: 50),                          // FPS < 50
    Tremor.jankRate(threshold: 10),                      // > 10% jank
    Tremor.pageLoad(threshold: Duration(seconds: 1)),    // > 1s load
    Tremor.memory(maxPillars: 30),                       // > 30 Pillars
    Tremor.rebuilds(threshold: 100, widget: 'QuestList'),// > 100 rebuilds
    Tremor.leaks(),                                      // Any leak suspect
  ],
);

// Listen for alerts via Herald
Herald.on<ColossusTremor>((event) {
  print('⚠️ ${event.message}');
});

Decree — Performance Reports #

Generate a comprehensive performance report:

final report = Colossus.instance.decree();

print(report.health);    // PerformanceHealth.good
print(report.summary);   // Full formatted report

// Drill into specifics
print(report.avgFps);
print(report.jankRate);
print(report.slowestPageLoad?.path);
print(report.topRebuilders(5));

Inscribe — Export Reports #

Export the Decree as Markdown, JSON, or a self-contained HTML dashboard:

final decree = Colossus.instance.decree();

// Markdown — great for GitHub issues, PRs, documentation
final md = Inscribe.markdown(decree);

// JSON — great for CI pipelines, dashboards, data analysis
final json = Inscribe.json(decree);

// HTML — self-contained visual dashboard (no external deps)
final html = Inscribe.html(decree);

Convenience methods on Colossus:

final md   = Colossus.instance.inscribeMarkdown();
final json = Colossus.instance.inscribeJson();
final html = Colossus.instance.inscribeHtml();

Save to Disk #

Use InscribeIO to persist reports to the file system (mobile, desktop, server — not web):

// Save individual formats
final path = await InscribeIO.saveHtml(decree, directory: '/tmp');
print('Report saved to $path');

// Save all three formats at once
final result = await InscribeIO.saveAll(decree, directory: '/reports');
print(result.markdown); // /reports/colossus-decree-20250115-100530.md
print(result.json);     // /reports/colossus-decree-20250115-100530.json
print(result.html);     // /reports/colossus-decree-20250115-100530.html

Lens Integration #

Colossus auto-registers two tabs in the Lens debug overlay:

Perf tab with sub-tabs:

• Pulse — Real-time FPS, jank rate, frame bar chart
• Stride — Page load history with timing
• Vessel — Pillar count, instance count, leak suspects
• Echo — Widget rebuild counts sorted by frequency
• Export — Copy/save reports in Markdown, JSON, HTML

Shade tab with controls for:

• Starting/stopping gesture recording
• Viewing last recorded session info
• Replaying sessions with progress tracking
• Viewing replay results

Shade — Gesture Recording & Replay #

Record real user interactions, then replay them as automated macros:

final shade = Colossus.instance.shade;

// Start recording
shade.startRecording(name: 'checkout_flow');

// ... user interacts with the app ...

// Stop and get the session
final session = shade.stopRecording();
print('Recorded ${session.eventCount} events');

// Save for later
final json = session.toJson();

// Replay while monitoring performance
final result = await Colossus.instance.replaySession(session);
final decree = Colossus.instance.decree();
print(decree.summary);

Wrap your app with ShadeListener to capture all pointer events:

ShadeListener(
  shade: Colossus.instance.shade,
  child: MaterialApp(...),
)

Text Input Recording

For text input recording and replay, use Spark's useTextController hook. When Colossus.init() is called, it automatically registers a factory that creates ShadeTextController instances — recording-aware controllers that capture every text change during a Shade recording session.

// In a Spark widget — text input is automatically recorded
class MyForm extends Spark {
  @override
  Widget build(BuildContext context) {
    final nameController = useTextController(fieldId: 'user_name');
    final emailController = useTextController(fieldId: 'user_email');

    return Column(
      children: [
        TextField(controller: nameController),
        TextField(controller: emailController),
      ],
    );
  }
}

The fieldId parameter enables accurate text replay — Phantom matches recorded text events to the correct field by ID. Without fieldId, Phantom falls back to injecting text into the currently focused field.

Widget Detection — TableauCapture & Glyphs #

TableauCapture walks the live Flutter Element tree and extracts Glyphs — standardized representations of every meaningful widget on screen. These Glyphs feed into Shade recordings, Scout analysis, and Scry observation.

Supported Interactive Widgets

The following widget types are automatically detected as interactive and captured with their label, bounds, enabled state, and interaction type:

Label Extraction

Labels are extracted automatically in priority order:

1. Child Text widget — ElevatedButton(child: Text('Save')) → "Save"
2. Decoration hint/label — TextField(decoration: InputDecoration(labelText: 'Email')) → "Email"
3. Tooltip or semantic label — IconButton(tooltip: 'Delete') → "Delete"
4. Semantics label — Semantics(label: 'Close menu') → "Close menu"
5. Widget key — GestureDetector(key: ValueKey('avatar-tap')) → "avatar-tap"
6. Positional fallback — GestureDetector(onTap: ...) → "tap@120,340"

Steps 5–6 ensure that GestureDetector and InkWell widgets without text children are still discoverable by Scry. For best results, add a Key to interactive widgets that wrap non-text children:

// ✅ Discoverable by Scry via key
GestureDetector(
  key: const ValueKey('profile-avatar'),
  onTap: () => navigateToProfile(),
  child: CircleAvatar(backgroundImage: userImage),
)

// ⚠️ Still discoverable, but targeted by coordinates
GestureDetector(
  onTap: () => navigateToProfile(),
  child: CircleAvatar(backgroundImage: userImage),
)

Visible Content Widgets

These widgets are captured as non-interactive content (display-only):

Text, RichText, Image, Icon, AppBar, Card, Dialog, AlertDialog, SimpleDialog, SnackBar, BottomSheet, Chip, Badge, Banner, Tooltip, Drawer, CircularProgressIndicator, LinearProgressIndicator, ErrorWidget

All other widgets (Container, Padding, Row, Column, Center, Align, Builder, etc.) are classified as layout noise and skipped.

Deduplication

Material buttons produce nested interactive layers (e.g., FilledButton → InkWell → GestureDetector). TableauCapture automatically suppresses inner layers that share the same label, so each logical button produces exactly one Glyph.

Scry — AI Agent Interface #

Scry gives AI assistants (via MCP) live vision of the running app. Instead of executing pre-written Campaigns, the AI observes the screen, decides what to do, acts, and observes the result.

The Agent Loop

scry (observe) → AI decides → scry_act (act) → scry_diff (compare) → repeat

Observing

const scry = Scry();
final gaze = scry.observe(glyphs, route: '/login');

gaze.buttons;     // Tappable elements (ElevatedButton, GestureDetector, InkWell, ...)
gaze.fields;      // Text inputs with current values
gaze.navigation;  // Tab bars, nav items
gaze.content;     // Display-only text and images
gaze.gated;       // ⚠️ Destructive actions (delete, remove, reset)
gaze.screenType;  // ScryScreenType.login, .form, .list, etc.
gaze.alerts;      // Errors, warnings, loading indicators
gaze.dataFields;  // Detected key-value data pairs
gaze.suggestions; // Context-aware action recommendations

Screen Types

Element Classification

Acting

{"action": "tap", "label": "Sign Out"}
{"action": "enterText", "label": "Hero Name", "value": "Arcturus"}
{"action": "longPress", "key": "profile-avatar"}

Targeting supports label (display text), key (widget Key), or positional labels ("tap@120,340") for elements without visible text.

Scout — AI Test Discovery #

Scout passively analyzes Shade sessions to build a Terrain — a live map of every screen the user visited and every transition between them:

final scout = Scout.instance;

// Analyze a completed recording session
scout.analyzeSession(session);

// Access the discovered terrain
final terrain = scout.terrain;
print(terrain.outposts.length);  // Number of unique screens
print(terrain.marches.length);   // Number of transitions

// Export as Mermaid diagram or AI-ready map
final mermaid = terrain.toMermaid();
final aiMap = terrain.toAiMap();

Scout learns incrementally — each new session enriches the existing Terrain with new routes, transitions, and reliability data.

Terrain — Flow Graph #

Terrain is a directed graph of Outposts (screens) connected by Marches (transitions). It auto-detects dead-ends, low-reliability edges, and orphaned screens:

final terrain = scout.terrain;

// Find a specific screen
final quest = terrain.findOutpost('/quest/details');

// Check screen health
print(quest?.deadEnd);         // true if no outgoing transitions
print(quest?.visitCount);     // How many times the screen was visited
print(quest?.reliability);    // Transition success rate (0.0 → 1.0)

Gauntlet — Edge-Case Test Generation #

Gauntlet auto-generates Stratagems (test plans) targeting weak spots discovered by Scout:

final gauntlet = Gauntlet(terrain: scout.terrain);

// Generate stratagems for a specific screen
final stratagems = gauntlet.forOutpost('/quest/details');

// Generate stratagems for the entire terrain
final all = gauntlet.forAll();

for (final s in all) {
  print('${s.name}: ${s.steps.length} steps');
}

Campaign — Test Execution #

Campaign orchestrates multi-step test runs with lifecycle management:

final campaign = Campaign(
  stratagems: gauntlet.forAll(),
  onSetup: () async => initTestEnvironment(),
  onTeardown: () async => cleanupTestEnvironment(),
);

final debrief = await campaign.execute();

print(debrief.passRate);           // e.g. 0.85
print(debrief.failedVerdicts);     // List of failed step results
print(debrief.fixSuggestions);     // AI-ready fix recommendations

Lineage — Route Resolution #

Lineage resolves parameterized routes back to their registered patterns:

final parameterizer = RouteParameterizer();
parameterizer.registerPattern('/quest/:id');
parameterizer.registerPattern('/hero/:heroId/quest/:questId');

final resolved = parameterizer.resolve('/quest/42');
print(resolved); // '/quest/:id'

Zero-Code Integration #

With ColossusPlugin, everything wires itself automatically:

1. Shade → Scout: Every completed recording is auto-fed to Scout
2. Atlas → Scout: Route patterns are pre-seeded from Atlas's trie
3. Atlas Observer: Page-load timing via ColossusAtlasObserver
4. Shade.getCurrentRoute: Auto-wired from Atlas for screen identification
5. Terrain Notifier: UI auto-refreshes when new sessions are analyzed

// That's it — one plugin, zero manual wiring
ColossusPlugin(
  tremors: [Tremor.fps(), Tremor.leaks()],
)

Blueprint Lens Tab #

The Blueprint tab adds a 5-sub-tab interactive interface to the Lens overlay:

• Terrain — Mermaid graph visualization, AI map export, conflict detection
• Stratagem — Browse auto-generated test plans with expandable detail cards
• Verdict — Step-by-step test results with pass/fail/skip rows
• Lineage — Route resolution metrics and Signet analysis
• Campaign — Campaign execution details with debrief summaries

BlueprintExport — AI-Bridge Export #

Export the complete Blueprint (Terrain + Stratagems + Verdicts) to disk so AI assistants like Copilot and Claude can consume it at IDE time:

// Live export from the current Scout state
final export = BlueprintExport.fromScout(scout: Scout.instance);

// Save to .titan/ directory
await BlueprintExportIO.saveAll(export, directory: '.titan');
// → .titan/blueprint.json       (structured data)
// → .titan/blueprint-prompt.md  (AI-ready Markdown summary)

Auto-Export on App Shutdown

Set blueprintExportDirectory on ColossusPlugin and Blueprint data is automatically exported when the app shuts down:

ColossusPlugin(
  blueprintExportDirectory: '.titan',
)

Offline Export from Saved Sessions

Use the CLI tool to build a Blueprint from previously saved Shade sessions:

# Basic export (run from your project root)
dart run titan_colossus:export_blueprint

# With options
dart run titan_colossus:export_blueprint \
  --sessions-dir .titan/sessions \
  --output-dir .titan \
  --patterns /quest/:id,/hero/:heroId \
  --intensity thorough

# AI prompt only
dart run titan_colossus:export_blueprint --prompt-only

Blueprint MCP Server

Expose Blueprint data to AI assistants via the Model Context Protocol:

{
  "github.copilot.chat.mcpServers": {
    "titan-blueprint": {
      "command": "dart",
      "args": ["run", "titan_colossus:blueprint_mcp_server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Available MCP tools:

• get_terrain — Full navigation graph (json, mermaid, or ai_map format)
• get_stratagems — Generated test plans (filterable by route)
• get_ai_prompt — AI-ready Markdown summary
• get_dead_ends — Screens with no outgoing transitions
• get_unreliable_routes — Transitions with low reliability scores
• get_route_patterns — Registered parameterized route patterns

Ecosystem Integration #

Architecture #

┌─────────────────────────────────────────────┐
│                 Colossus                     │
│              (Pillar singleton)              │
├──────────┬──────────┬──────────┬────────────┤
│  Pulse   │  Stride  │  Vessel  │   Echo     │
│  (FPS)   │ (Loads)  │ (Memory) │ (Rebuilds) │
├──────────┴──────────┴──────────┴────────────┤
│  Shade (Record & Replay) │ Inscribe (Export)│
├──────────────────────────┴──────────────────┤
│            AI Blueprint Generation           │
│  Scout → Terrain → Gauntlet → Campaign       │
│  Lineage │ Stratagem │ Verdict │ Debrief     │
├─────────────────────────────────────────────┤
│              AI-Bridge Export                 │
│  BlueprintExport │ ExportIO │ MCP Server     │
│  CLI Tool │ Auto-Export │ AI Prompt          │
├──────────┬──────────┬──────────┬────────────┤
│  Herald  │Chronicle │  Vigil   │   Lens     │
│ (Events) │ (Logs)   │ (Errors) │  (UI Tab)  │
└──────────┴──────────┴──────────┴────────────┘

License #

MIT — see LICENSE.