Performance with Constraints

Constraints are designed to be deterministic and debuggable, but they still have a cost model. This guide explains what matters in real apps.

See also:

• docs/guide/performance.md
• docs/dev/testing.md (perf and audit gates)

Cost model (what you pay for)

1. Parsing: expr("...") parses DSL text into a frozen AST.
2. Graph build: expressions referencing parent/viewport/#id/intrinsic participate in a dependency graph.
3. Resolution: expressions are evaluated deterministically against resolved ref values.
4. Layout: resolved numbers flow into the layout engine.

Helper constraints compile to expr("..."), so they share the same underlying work.

Implementation note: expr("...") is cached by source string (small LRU), so repeating the same expression source does not re-parse each frame.

Best practices

• Prefer helpers: they reduce mistakes and keep expressions simple.
• Hoist stable constraints out of hot render paths when practical:

const showRail = visibilityConstraints.viewportWidthAtLeast(110)

app.view(() => ui.box({ display: showRail }, [...]))

• Avoid generating lots of unique expression strings per frame (for example string concatenation with varying numbers).
• Use steps(...) or a small number of discrete breakpoints rather than many micro-variants.

When to simplify

If you’re using constraints for something that’s naturally expressed by:

• flex
• fixed sizes
• fluid(...)

…switch back to those simpler primitives. Constraints are for relationships, not for everything.

Validation tools

• Run the full deterministic test suite:
  • npm run build
  • node scripts/run-tests.mjs
• Use frame-audit when changing layout/constraints:
  • docs/dev/live-pty-debugging.md