morphos_ui

A flat, matrix-driven UI field for Flutter. Hundreds or thousands of nodes (cards, tiles, chips, image thumbnails) live in one render object instead of a widget tree. One affine matrix lays them out, a built-in spring solver animates them, and they are painted with Canvas.drawVertices.

MorphOSField(
  spec: isGrid ? gridSpec : listSpec,          // swap the spec → everything springs
  onNodeTap: (id, index) => print('tapped $id'),
)

dependencies:
  morphos_ui: ^0.1.0

final spec = MorphFieldSpec.grid(
  width: 400,              // design units; the field scales to its box
  columns: 3,
  nodes: [
    for (var i = 0; i < 60; i++)
      MorphNodeSpec(
        id: i,             // stable id: how nodes are matched across specs
        size: Size.zero,   // grid() fills in size and position
        color: Colors.indigo,
        cornerRadius: 12,
        text: 'Card $i',
        maxLines: 2,
      ),
  ],
);

MorphFieldSpec.list(...) and MorphFieldSpec.stack(...) work the same way. You can also place nodes by hand:

• anchor works like Alignment over the design size. (0, 0) puts the node's top-left at the origin and (1, 1) puts its bottom-right in the far corner.
• position is an extra offset in design units.

Each node has its own spring:

• elasticity: stiffness, higher is snappier.
• mass: higher is heavier and slower.
• dampingRatio: 1 settles without bounce, below 1 bounces.

Supply a new spec and every node with the same id moves from wherever it is now, keeping its velocity. New ids grow in and missing ids shrink out (animateEntryExit).

Stagger the start times:

stagger: MorphStagger.fromPoint(tapCentre),   // ripple out from a point
stagger: MorphStagger.byIndex(Duration(milliseconds: 20)),

The solver integrates at a fixed 1/240 s step, so the result is identical at 60, 120 and 144 Hz. A long frame (jank, a breakpoint) is clamped to 1/30 s, so nothing jumps. When the platform asks for reduced motion (MediaQuery.disableAnimations), changes snap instead. A resting field schedules no frames and does no repaints.

• onNodeTap(id, index): also fires on Enter or Space while a node has keyboard focus.
• onNodeHover(id): mouse hover. The mouse cursor switches to nodeCursor over interactive nodes.
• draggable: true nodes follow the pointer. On release they keep their fling velocity and spring back, unless your onNodeDragEnd supplies a new spec that moves them.
• enableScroll: true scrolls by drag, fling or mouse wheel, with a rubber-band edge. It's vertical by default (use MorphFit.fitWidth). Set scrollDirection: Axis.horizontal with MorphFit.fitHeight for a sideways strip.
• Keyboard: Tab and Shift-Tab move through nodes in reading order, and arrow keys move to the nearest node in that direction. Focus leaves the field at either end.
• Semantics: every node with semanticLabel or text becomes an accessibility node with its own rect and a tap action. Screen readers can also scroll the field a page at a time.
• Right-to-left: under an RTL Directionality, node positions and rotations mirror, and switching direction springs nodes across. Text and images are not flipped. Turn it off with mirrorInRtl: false.

final controller = MorphController();

MorphOSField(
  spec: spec,
  enableScroll: true,
  controller: controller,
  onSettled: () => print('everything is at rest'),
);

await controller.scrollToNode(42, alignment: 0.5); // spring it to the middle
controller.jumpTo(0);
final rect = controller.nodeRect(42);              // where it rests on screen
final id = controller.nodeAt(localPosition);       // what is under a point
await controller.whenSettled();

MorphController is a plain ChangeNotifier (part of Flutter): listeners hear about scroll changes and settling. Its only dependency is Flutter itself. A user drag interrupts a running animateTo / scrollToNode, which then completes.

MorphOSField(
  spec: spec,                                    // nodes use imageKey: 'hero'
  images: {'hero': AssetImage('assets/hero.png')},
)

Images are resolved and packed into one texture (up to 4096×4096), off the frame loop. A node with imageKey samples its part of the texture, tinted by imageTint. Images keep their proportions and crop to fill the node (imageFit: MorphImageFit.cover, the default), so a square photo in a wide card isn't stretched. MorphImageFit.fill stretches instead. Flat nodes sample a reserved white block, so both kinds share one draw call. If an image fails to load it is reported to onAtlasError, and that node falls back to its colour.

Scaling. Off-screen nodes are skipped in both paint modes, and screen readers get only nodes within one viewport of the visible area. The solver keeps an active set, so only moving nodes are integrated and checked each frame. spec.withNode(node) / spec.withNodes([...]) replace nodes by id while sharing the rest, and applying the result rewrites only the changed slots.

Paint order follows zIndex, with spec order breaking ties. In shapes mode each node's text is drawn right after its shape, so layering is exact. In vertices mode text is drawn after the meshes. The exception is a text node that another, later node covers at rest: the batch is split there so the later node covers the text. These splits are worked out once per spec change, not every frame.

benchmark/ compares five ways of animating N cards between a grid and a list (rounded corners, text up to 1,000 cards):

• MorphOS-UI, shapes mode (the default) and vertices mode.
• A hand-written CustomPainter with the same spring physics, cached TextPainters and no widget rebuilds. This is the fastest thing you'd write by hand, with none of MorphOS-UI's features.
• Flame, one component per card, animated with Flame effects.
• A widget tree: Stack + AnimatedPositioned + DecoratedBox + Text.

Setup: macOS desktop (Apple M3 Pro), profile mode, Flutter 3.47.6. Each contender does 4 morphs, each measured over a fixed 1.2 s window. The table shows the median of 4 runs; runs where macOS throttled the window in the background were discarded.

GPU raster time at 5,000 cards is about 0.36 ms for MorphOS-UI, the painter and Flame alike. Frames over budget per run at 5,000 cards: 0–1 for MorphOS-UI, the painter and Flame; 7–9 for the widget tree.

What this shows, and what it doesn't:

• MorphOS-UI is level with a hand-written CustomPainter at 5,000 cards and fastest at 100. At 1,000 cards the painter is about 20% faster. In return you get hit testing, keyboard focus, semantics, right-to-left support, scrolling, images and a controller, none of which the painter has.
• At 5,000 cards it is about 2× faster than Flame and the widget tree, and its p90 is less than half the widget tree's.
• The worst single frames in the table come from other processes on the test machine, not from MorphOS-UI. Timeline traces of the same 5,000-card morphs show both MorphOS-UI and the painter with no frame over 8 ms (worst 4.9 ms vs 5.1 ms; median 1.83 vs 1.75 ms). Applying a 5,000-node spec costs about 1.3 ms in total.
• MorphOS-UI still triggers more garbage-collection pauses than the painter (107 vs 62 over 6 morphs), because each layout change builds a new 5,000-node spec. That's the cost of describing layouts declaratively.
• shapes mode beats vertices mode on GPU time (0.36 vs 0.71 ms at 5,000 cards). That's why it's the default. Use vertices if you specifically need the batched, allocation-free path.
• Averages include frames after an animation has finished. That slightly favours the widget tree and Flame, whose animations are shorter (700 ms).
• Only measured on macOS so far, not on phones.

MorphOS-UI only draws what's on screen and only animates what's moving. That's where it pulls ahead. Two scenarios, same setup as above, cards in a scrolling 400-px-wide column:

• One card changes (moved with spec.withNode(...), the way an app would edit one item)
• All cards morph between grid and list

At 100,000 cards MorphOS-UI holds full frame rate and drops 2–3 frames per run, all on the layout-change frame (building and applying a 100,000-node spec takes about 60 ms). The painter drops most of its frames, and Flame drops all of them.

To be fair to the alternatives: a hand-written painter could skip off-screen items and still items too. MorphOS-UI does both for you.

Run it yourself (profile mode, on a real device); see benchmark/README.md for the timeline-trace and spec-cost runs:

cd benchmark
flutter drive --profile -d <device> \
  --driver=test_driver/perf_driver.dart \
  --target=integration_test/compare_test.dart

• Leaf render object: no child widgets inside the field.
• One scroll axis at a time.
• Text is drawn per node through cached paragraphs. Fades use a saveLayer while a text node is partly transparent.
• MorphEffect.sheen depends on fragment-shader support for drawVertices on the active renderer.

MIT