Let hosts pin the clock formulas read

FormulaClock.pinned sets the instant now() and today() (and relative
times) take, so a host can show an app at a given moment: previews of a
given day and reproducible screenshots of date-dependent screens.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F3B1XCZZ7QGvZLUGgSG5H4

Author: claude

lib/src/transformers/utils/property_value_delegate.dart

@@ -1081,7 +1081,7 @@ String formatDate(DateTime date) {
 /// Formats [date] relative to now: `Just now`, `5 min ago`, `2 hours ago`,
 /// `3 days ago`, then [formatDate] after a week.
 String formatTimeAgo(DateTime date, {DateTime? now}) {
-  final Duration diff = (now ?? DateTime.now()).difference(date);
+  final Duration diff = (now ?? FormulaClock.now()).difference(date);
   if (diff.inMinutes < 1) return 'Just now';
   if (diff.inHours < 1) return '${diff.inMinutes} min ago';
   if (diff.inDays < 1) {

lib/src/utils/formula.dart

@@ -996,12 +996,25 @@ Duration? _offset(Object? value) {
   return Duration(minutes: m[1] == '-' ? -minutes : minutes);
 }
 
+/// The instant formulas take as now (`now()`, `today()`).
+///
+/// A host can pin it to show an app at a given moment, for previews and
+/// reproducible screenshots of date-dependent screens (the Codelessly site
+/// pins it from a `?now=` URL parameter).
+abstract final class FormulaClock {
+  /// The pinned instant, or null for the device clock.
+  static DateTime? pinned;
+
+  /// Now: [pinned], or the device clock.
+  static DateTime now() => pinned ?? DateTime.now();
+}
+
 /// The wall-clock time now at the UTC [offset] (see [_offset]), or local
 /// time without one. Returned without a zone, like other formula dates.
 DateTime _nowAt(Object? offset) {
   final Duration? delta = _offset(offset);
-  if (delta == null) return DateTime.now();
-  final DateTime utc = DateTime.now().toUtc().add(delta);
+  if (delta == null) return FormulaClock.now().toLocal();
+  final DateTime utc = FormulaClock.now().toUtc().add(delta);
   return DateTime(
     utc.year,
     utc.month,

test/formula_clock_test.dart

@@ -0,0 +1,25 @@
+import 'package:codelessly_sdk/codelessly_sdk.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  tearDown(() => FormulaClock.pinned = null);
+
+  String eval(String formula) => FormulaEvaluator.stringify(
+    FormulaEvaluator.evaluate(formula, (path) => null),
+  );
+
+  test('a pinned clock is what now() and today() read', () {
+    FormulaClock.pinned = DateTime.parse('2026-10-22T13:20:00-07:00');
+    expect(
+      eval("formatDate(now('-07:00'), 'EEE, MMM d · h:mm a')"),
+      'Thu, Oct 22 · 1:20 PM',
+    );
+    expect(eval("formatDate(today('-07:00'), 'yyyy-MM-dd')"), '2026-10-22');
+    expect(eval("formatDate(now('Z'), 'HH:mm')"), '20:20');
+  });
+
+  test('without a pin, now() is the device clock', () {
+    final String year = '${DateTime.now().year}';
+    expect(eval("formatDate(now(), 'yyyy')"), year);
+  });
+}