flutterflow_flash_beta 0.1.5

Dart SDK for programmatically reading and modifying FlutterFlow projects. Built for the beta environment.

0.1.5

DSL — Greenfield

• Added public Gradient / GradientStop types and a Container.gradient parameter so linear gradients can be expressed without dropping into the internal UI layer.

DSL — Brownfield

• Added app.existingCollection() for referencing Firestore collections that already live on the project, with tests covering the full DSL surface.
• Added app.existingComponent() as a brownfield-oriented alias for projectComponent.
• Added setComponentParam() for binding parameters on existing component instances.
• Added editPageOnLoad() for attaching page-load actions to existing pages.
• Added ensurePage() for idempotent page creation across reruns.
• Added ensureFirebaseAuth() for idempotent Firebase Auth configuration, guarded at the DSL level.
• Added list/scalar shape validation and dynamic expression type checking for brownfield bindings.
• Added type validation for setComponentParam literals and existingCollection fields.
• Added subtype identity validation in existingCollection schema checks.
• Fixed listOf() to propagate subType to the outer FFDataTypeV2 so FF validation recognizes typed lists.
• Improved brownfield validation error messages and cleared stale isList state when re-validating.
• Widened BrownfieldWidgetPatch with margin, alignment, border, shadow, and opacity. Margin is applied via a rerun-stable structural wrapper (<Target> Margin) so repeated patches do not double-wrap.
• Added BrownfieldParamEditor.updateParam(name, {type, description}) for partial type/description drift on existing params.
• Added BrownfieldWidgetEditor.mutateNode(selection, mutate) as a typed escape hatch for raw FFNode property mutations not yet exposed through the patch surface.

DSL — Removals

• Added 14 public remove APIs on App: removePage, removeComponent, removeCollection, removeTable, removeDataStruct, removeEnum, removeCustomFunction, removeCustomAction, removeCustomWidget, removeActionBlock, removeAppEvent, removeSpacingToken, removeRadiusToken, removeShadowToken. Project-level deletion is intentionally excluded.
• removeX now fails fast when the same App also declares (e.g. app.page('Foo', ...)) or references (existingCollection, existingComponent, projectComponent, the editPage*/editComponent* family, and the ensureX brownfield pattern helpers) the same name. Previously the removal would silently undo the declaration or leave compiled references dangling.

DSL — Component handles

• Component-handle invocation now accepts reserved name: and visible: arguments and forwards them to the underlying ComponentInstance, e.g. tripCard(title: 'Paris', name: 'HeroTripCard'). Unknown component params still throw.
• Component declarations (component, projectComponent, existingComponent, libraryComponent) reject params named name or visible since those keys are now reserved for instance metadata.

Pipeline — Phase 1 stabilization

• Restored the previous export on failed atomic swap so a failed push no longer leaves the workspace in a half-written state.
• Redacted local filesystem paths from shareable artifacts and trace-derived support bundles (extending the 0.1.4 redaction pass to the remaining artifact types).
• Rejected blank MCP tool configuration entries instead of silently accepting them.
• Closed remaining Phase 1 safety gaps around backups, redaction completeness, and config validation.

CLI

• flash refresh-workspace now runs dart pub get after refreshing so the workspace is immediately usable.

Features

• Added Copy Flash Selector for deterministic widget targeting by agents (#7196).
• Ungated the GenUI chat widget (#7197).

Docs

• Added a brownfield data-binding reference and updated agent docs (CLAUDE.md, AGENTS.md) to link to it instead of inlining API documentation.

0.1.4

• Export a local generated_code/ snapshot during flash init --project <id> when flutterflow CLI is installed, reuse the same project ID, API token, and base URL as Flash, and run flutter pub get inside that snapshot when Flutter is available.
• Request the generated-code export manifest during flash init --project <id> when the installed flutterflow CLI advertises --include-export-manifest, so future CLI releases can drop entity-to-file mappings directly into the workspace snapshot.
• Mark generated-code snapshots as stale after successful pushes, persist freshness metadata under .flash/generated_code_state.json, and add flash codegen status plus flash codegen refresh for explicit refresh workflows.

CLI

• Fixed flash status and flash search temp-script execution so package resolution and internal SDK calls succeed reliably.
• Fixed flash inspect mode routing and normalized sub-mode runtime failures so --outline, --tree, --debug, and --deep now fail consistently with exit code 1.
• Added flash docs ui as a valid docs alias.
• Added flash --version / flash -v.
• Made bare flash print help and exit successfully.
• Fixed flash plan save <path> so missing files fail instead of saving the path string as plan contents.
• Normalized expected CLI failures to clean error output instead of raw Dart stack traces.
• Treated blank FF_BASE_URL values in .env as unset and updated the generated .env.example to use a commented local-dev override instead of an empty assignment.
• Added a real example/ directory and included it in staged pub.dev publishes so the published package has a runnable example.

Pipeline

• Aligned greenfield dry-run with the real project-creation baseline to reduce validate-vs-run drift.
• Avoided persisting workspace bindings for newly created projects when flash run fails before a successful push.
• Redacted local filesystem paths from support bundles and trace-derived bundle artifacts.

DSL

• Fixed brownfield existing-widget compilation so bindings and actions can resolve custom functions already present on the project.
• Fixed brownfield existing-widget compilation so newly declared custom functions in the same patch can be used in bindings, SetState, nested Struct(...) payloads, and UpdateAppState.
• Fixed brownfield existing-project type import so app/page/component state using ImagePath and List<ImagePath> no longer crashes compilation.
• Fixed brownfield existing-project type import so app/page/component state using VideoPath, AudioPath, DocumentReference, and list variants no longer crashes compilation.
• Added asset_and_reference_surface_dsl.dart as a consolidated reference for imagePath, videoPath, audioPath, docRef(...), and list-based asset/reference state usage in Flash.

0.1.3

• Fix beta package README install/import examples so the pub.dev package page consistently uses flutterflow_flash_beta for activation, dependency setup, and code imports.

0.1.2

• Fix hosted/pub.dev Flash pipelines so beta builds honor the published staging base URL on flash() and flash run instead of falling back to prod unless --base-url is passed explicitly.
• Fix hosted MCP execution so published Flash packages invoke the CLI through dart pub global run <package>:flash and resolve the package root using published package metadata instead of local package:flash assumptions.
• Fix publish dry-run validation by removing staged analyzer warnings and aligning package analysis settings with the published package surface.

0.1.1

• Fix flash refresh-workspace --yes so it repairs workspace MCP registrations and refreshes the generated launcher scripts for supported CLIs.
• Generate hosted pub.dev dependencies for pub-activated Flash installs and rewrite stale pub-cache path: dependencies during workspace refresh.
• Forward --find-or-create through the generated push wrapper and stop persisting workspace project bindings after failed runs.
• Serve the README hero banner from a hosted URL and stop bundling README-only banner assets in staged pub.dev publishes.

0.1.0

Initial release.

Core SDK

• SDK client with session management (lock/unlock), project CRUD, and schema validation.
• 16+ helper modules: collections, pages, components, action blocks, app events, custom code, data schemas, enums, data structs, app state, queries, themes, APIs, library parameters, library values, widget class parameters, nav bar, routing, widget properties, tree mutation, pub dependencies, variable operations, state updates, graph analysis.
• 18 idempotent ensure* helpers (ensurePage, ensureCollection, etc.) for re-runnable pipelines — exact reruns return the existing identifier/key, while payload drift throws and should be handled with update* helpers or onUpdate:.
• 14 update* helpers for full CRUD coverage: updateCollection, updateCollectionField, updateDataStruct, updateDataStructField, updateEnum, updateEnumValue, updateAppStateField, updateAppConstant, updateActionBlock, updateApiEndpoint, updateApiGroup, updatePageParameter, updateComponentParameter, updateStateField.
• updatePageBody and updateComponentBody to replace widget trees in place.
• Enhanced "not found" error messages across helpers — lists available names for self-correction.
• FlashApiException.hint with recovery guidance for 409 (lock), 403 (auth), and 404 (not found) errors.
• listProjects() uses dedicated sdkListProjects endpoint with API token auth.
• Local validation via pre-compiled .dill kernel snapshots (no server round-trip).

DSL

• Declarative Dart DSL for building FlutterFlow apps: flash(builder) compiles and pushes in one call.
• Greenfield: define pages, components, enums, data structs, app state, API endpoints, and widget trees from scratch.
• Brownfield: editPage / editComponent for structural edits against existing projects — select widgets by key, name, type, or text, then insert, replace, remove, or rewire.
• DSL JSON snapshots (dsl_json/) — machine-readable project context written to disk on push, refresh-context, and workspace init. flash inspect reads from these for instant offline access.

Pipeline

• FlashPipeline + FlashTask for modular, dependency-aware task execution with automatic lifecycle management (lock → fetch → run tasks → validate → push → capture resulting commit → release).
• PipelineProject.findOrCreate(name) to reuse existing projects by name on re-run.
• PipelineSource for mandatory source code upload with pipeline runs.
• Per-task local validation — error-severity issues halt the pipeline immediately; subsequent tasks are not executed and push is blocked.
• Validation gates push — broken projects never reach FlutterFlow. Check result.validationBlocked and result.errors. result.diagnostics is the primary error surface.
• Dry-run mode (FlashPipeline(dryRun: true)) to preview changes without pushing.
• Greenfield runs auto-prune the untouched blank HomePage placeholder that brand-new FlutterFlow projects start with.
• Workspace state (.flash/workspace.json) — caches project ID, records per-task pass/fail/skip/validation_failed status.
• Local run journal and source archival — every run journaled to .flash/runs.jsonl with source files archived to .flash/history/<run-id>/.
• Canonical RunTrace artifacts in .flash/traces/<run-id>.json.
• Support bundle export and support replay workspace reconstruction.
• Local derived issue candidates built from repeated trace evidence.

UI Builder

• 50+ declarative widget builders for layout, text, input, buttons, lists, tabs, cards, forms, and more.
• Actions API for navigation, snack bars, Firestore CRUD, event triggers, and flow control (conditional, terminate, loop, parallel, nonBlocking).
• Design token system with theme-aware colors, spacing, radii, and shadows.
• Variable binding: 8 variable sources, operations, state updates.
• GenUI chat widget support: UI.genUiChat() builder and genui_helpers.dart module (24 functions) — expose action blocks as AI tools, manage catalog components, configure chat UI, subscribe to app events for context injection.

CLI

• flash init <name> — scaffold a new workspace with pubspec, CLAUDE.md, AGENTS.md, starter app and brownfield patch. Runs dart pub get automatically.
• flash run [file] — execute a pipeline or DSL script (loads .env, default: flash/app.dart).
• flash status <project-id> — show project summary.
• flash inspect <project-id> — DSL JSON snapshot for the project, a specific page (--page), or component (--component). Reads from on-disk dsl_json/ snapshots when available, falls back to API. Also supports --debug (consolidated report), --outline (ASCII tree), and --deep (PROJECT_CONTEXT.md-style).
• flash validate <file> — validate a DSL script without pushing (exits 1 on errors).
• flash refresh-context <project-id> — update PROJECT_CONTEXT.md, context/, and dsl_json/ snapshots.
• flash refresh-workspace — overwrite Flash-managed docs (CLAUDE.md, AGENTS.md, references/, patterns/, tooling/).
• flash context-check — check context freshness (local + optional server comparison).
• flash resources <project-id> — emit reusable project, library, and theme resources as machine-readable JSON.
• flash search <project-id> --query <text> — fuzzy entity search.
• flash docs [topic] — browse SDK documentation.
• flash history / flash history show <run-id> — view past runs and recover archived source.
• flash trace latest|show|export — inspect and export canonical run traces.
• flash support case|inspect|bundle|replay — support-oriented case assembly, inspection, bundle export, and replay workspace reconstruction.
• flash issue candidates|show — derive repeated local issue signals from traces.
• flash plan / flash plan save / flash plan clear — manage active plan.
• --api-key <key> flag on all commands as an alternative to FF_API_KEY env var.

MCP Server

• Exposes Flash CLI as structured tools for AI agents (Claude Code, Gemini CLI, etc.): init, status, search, inspect, validate, refreshContext, contextCheck, run, docs, history.

Testing

• 2,600+ unit tests across client, helpers, pipeline, DSL, and UI layers.
• Integration test helpers: addTestGroup, addTest, given/when/then steps, widget finders.