How a widget type is added to the SDK, and where each part of the runtime
lives. Read the model's design first:
CodelesslyAPI/DESIGN.md.
- Declaration (
codelessly_api, pure Dart):CodelesslyAPI/lib/src/widgets/<group>.dart. OneWidgetSpecper type in<group>Specs, withPropDefs that use Flutter's parameter names, types and defaults (look at the Flutter widget the node maps to). Nested models get small immutable value classes (withfromJson/toJson/==, total decoding, sparse encoding), in the same file or a<group>_models.dartnext to it. Never import Flutter. Prefer a Flutter name for the type (textField,slider,listView). - Recipe (this package):
lib/src/widgets/<group>.dart, aWidgetRecipeper type in<group>Recipes. Seelib/src/render/recipe.dartfor theNodeBuilderAPI:b.fitBox,b.shell,b.flex,b.freeform,b.syncChildrenbuild with render objects, like the core types inlib/src/render/node_tree.dart. Prefer render objects: a widget that's only layout and paint (dividers, progress bars, gauges, list layouts) is render objects.b.island(key, (context) => widget)hosts a real Flutter widget for what needs an element tree (text fields, sliders, dropdowns, video, web views, charts). Child nodes inside an island:NodeChild(tree: b.tree, id: childId, instance: ...).- Repeated templates (list/grid items in preview):
b.syncChildren(..., instance: (b.id, index))gives each repetition its own boxes;instances:(one per id) scopes each item on its own. Leave the first repetition unscoped (null): the goldens, like the editor, measure a template at its first instance (tree.boxOf(id)). The outer layers (margin, constraints, behaviors such as motion, scale and loops, rotation, opacity, blurs, aspect ratio; seelib/src/render/behaviors.dart) are already added by the tree; build the widget's content inside them.
- Tests: unit and widget tests.
lib/src/runtime/expressions is the ${...} language (the formula
evaluator, paths and accessors), the value scopes (VariableScope,
ItemScope, ValuesScope), conditions, and NodeBinder: give a
NodeTree a binder (NodeTree(source, binder: NodeBinder(scope: ..., logic: doc.logic))) and each node is shown through its bindings; a
variable change re-applies only the boxes that read it. preview: true is
the design canvas (placeholders for ${...} in text). A recipe that reads a
bound prop needs nothing more: it gets the node already bound.
samples-bindings is the runtime golden set (rendered with the
pages' variables and conditions).
lib/src/runtime/actions runs reactions (Reaction, ActionDef;
DESIGN.md §5.2): CodelesslyActions is the ActionRunner, with one typed
handler per action type (handlers.dart) over an ActionContext
(RuntimeActionContext: scope, expressions, services, an ActionUi, the
node tree, NodeValues). Give a tree TreeReactions(runner:, context:) as
its interactions and, while a NodeView(interactive: true) shows it, its
nodes react: taps, long presses, hover and swipes are recognizers in a
RenderReactions layer of the node's chain; load, timers, value changes
and keys live with the box; viewport triggers are checked after frames. A
recipe whose island takes input reports it with fireTrigger(b, 'changed', event: {'value': v}) (inputs.dart, material.dart): the runtime writes the
value to the variable the input's value is bound to and runs the node's
reactions. A type whose island takes taps itself is in selfTappedTypes.
lib/src/runtime/gestures: physics.dart is the one release physics
(GesturePhysics/GestureSnap: springOf, rubberBand,
boundsRange, AxisSettleSimulation, snapTargetOf, SimulationGroup);
build every gesture's release on it. drag_motion.dart is a node that
follows the pointer (RenderDragMotion, the outermost layer;
DragMotionControl for controlDrag), drag_and_drop.dart drag sources
and drop targets (RenderDragSource, RenderDropTarget before the
reactions; DragAndDrop.of(tree) is the session ${drag} reads; a list
opens dropSlotOf(tree, listId)). Only an interactive tree adds them. A
behavior that gives the nodes inside it names (drag) registers in
NodeBinder.localNames and sets its LocalScope
(binder.localScopeOf). runTrigger fires a trigger and waits for its
chain.
A behavior that takes the pointer is a render object of the node's chain,
configured on each apply with the node as shown (bindings applied) and its
NodeBox (render/behaviors.dart creates it; animates: false, the
design canvas, gets the rest pose or no layer, never a recognizer or a
ticker): RenderDragTrack (render/drag_track.dart), RenderTransformGesture
(render/transform_gesture.dart), RenderFlip (render/flip_card.dart).
They read and watch their variables in the node's scope
(binder.scopeFor), write them with setVariableIn, and fire the node's
reactions with fireTrigger(box, ...) ({'result': ...}).
- Node scopes (runtime/expressions/node_scopes.dart): a node whose
behavior declares names (
track,transform,flip,tilt) gets oneNodeValuesScopebetween the scope around it and its nodes'; its render object writes it (binder.nodeScope(...).update(name, map)), never while painting (from events and ticks; fromconfigureafter a microtask). A new kind adds a declarer tonodeScopeDeclarersand todeclaresNodeScope. - Hits beyond the node's box (a track's area or parent hit area, a
moved node, transform handles): set
NodeBox.outsideHitTestin the layer's configure (reset on each apply). - Actions on a node's live state: a registry by tree
(
DragTracks.step,TransformGestures.reset) the handler reaches throughrun.host.tree. - Focus: a FocusNode attached to the view's element
(
IslandParent.islandContext), so Tab and the keys reach a track.
lib/src/runtime/lists is pagination (PaginationController,
PaginationRegistry.of(tree), the page sources, the paginate action) and
the reorder helpers. A list's running features are islands built only while
the tree animates (collections_data_list.dart, collections_reorder.dart,
collections_swipe.dart, collections_table.dart, over
collections_list_runtime.dart's ListRuntime): their repeats are
NodeChild boxes whose instance is a ProvidedItem, given its item with
NodeBinder.provideItem (an island's item, unlike a bound list's, isn't
read from the list's data by index). Fire a list's triggers through
ListRuntime.fire (awaits them: pull to refresh shows until they end).
Node boxes aren't hit themselves: wrap a row that gestures read in an
opaque MetaData.
Scripts (lib/src/scripting): the
driver (script_driver.dart, the JS host API and lockdown) runs in
QuickJsSandbox (FFI to codelessly_quickjs's library) or WorkerSandbox
(web), picked by conditional import; SandboxScriptRunner speaks its
protocol over a ScriptHost (RuntimeScriptHost for a chain,
SampleScriptHost for the editor's console) and runs a script's test cases
(runScriptTests). ScriptsScope (between a screen's fixed values and its
variables) answers script.name(args) in formulas. Tests run real scripts:
test/scripting/support/engine_setup.dart builds the library with
tool/build_quickjs.sh (CMake, a C compiler) on first use.
- Toasts and the confirm dialog (
runtime/actions/toast.dart,confirm_dialog.dart) draw the action'slookover the app's look (FeedbackTheme: the app's extension, then the layout's, read by the shell from its tokens and nodes,FeedbackTheme.fromDocument). The handler evaluates text andvariableswhere the action runs and passes them toActionUi.showToast/confirm(bound). Modals the runtime opens wrap their content inToastBelowRoute;ToastOverlayScopekeeps an embedded app's toasts in its own overlay. - Heroes: there's no widget per node for Flutter's
Hero. ARenderHeroMarkin the node's chain (render/hero.dart, inside rotation and motion) registers per tree; the shell binds each tree to its route (HeroRoutes.bind); the shell's routes mix inCodelesslyHeroRoute(CodelesslyPageRoute,CodelesslyPageTransitionRoute,CodelesslyRouteTransitionRoute) and fly the matching tags in the navigator's overlay (runtime/actions/hero_flights.dart): both ends hide, aHeroMarkPaintpaints the borrowed box stretched over the box in between. The node isn't laid out again at the in-between size (it's scaled). A host route that isn't one of these doesn't start flights, but can be the screen they fly from or to. effectAnimations(render/play.dart,RenderEffects, outside motion):playAnimation(EffectPlayers.play), a changed boundplayKey, orplayOnAppear. A hero that flies in place (herowithflies: inPlace):RenderFlightBoxrecords where it's drawn (FlightRegistry,recordDropfor a drag let go) and springs in (or flies as itsflightsays) from where another holder of its tag was. Particles aren't drawn yet.- Navigation (
app/navigation.dart): optional trailing params (:id?),CanvasLocation.defaultPathOf(the path the editor publishes for a screen without one), a link by id named at the screen's path (CanvasLocation.named, used byonGenerateRoute), page transitions (app/page_transitions.dart; the platform's is none on the web).
See the model's DESIGN.md §5.4 and §5.3.
- Loading (
app/loader.dart,services/firebase/publish_loader.dart): the publish is read from the publish paths (publish/{project}, itslayouts/{id};publish_preview,templates), in the current format (schema: 2,compressedNodes:decodeStoredPublishModel,decodeStoredPublishLayout).FirestorePublishLoaderauthenticates with the project token (ProjectAuth, theverifyProjectAuthTokenbackend call) and is aLivePublishLoader(it follows the model document);codelesslyOnFirebasesets an instance up on it. A slug reads its bundle over HTTP (publish/{slug}.json). Tests:test/services/ firestore_publish_loader_test.dartonfake_cloud_firestore, with documents in the stored format. - Breakpoints: one project set (
PublishModel.breakpoints) and a node's or screen canvas's own switch points (VarianceProps.minWidths,CanvasBreakpoint.minWidth). Variances resolve withBreakpoints.forWidth(w, minWidths)thenBreakpoints.governing(the nearest breakpoint on the defaults), screens pick canvases by their switch points,${screen}inside an overriding variance follows its widths (ResponsiveScreenScope), an adaptive Open Modal is a sheet belowOpenModalAction.sheetBelowWidthIn(breakpoints)(an adaptive confirm belowdefaultSheetBelowWidth, the second breakpoint).
- The core (
node_tree.dart,recipe.dart,node.dart,props.dart...) is shared: keep changes there minimal and additive. dart analyzeclean in both packages;flutter testanddart testgreen.dart run tool/fast_test.dartruns the SDK's whole suite in under half a minute: it bundles the test files into a few shard files, so Flutter compiles and starts two dozen processes instead of one per file (flutter testalone takes about twice as long). Give it paths to run a part (dart run tool/fast_test.dart test/tool); what follows--goes toflutter test. A test file that only passes in a process of its own is listed at the top of the script.