add timeline pkg to flutter

packages/z-timeline/lib/src/constants.dart

@@ -0,0 +1,24 @@
+import 'package:flutter/material.dart';
+
+/// Shared layout constants for the z_timeline package UI.
+class ZTimelineConstants {
+  const ZTimelineConstants._();
+
+  // Heights
+  static const double laneHeight = 28.0;
+  static const double groupHeaderHeight = 34.0;
+
+  // Spacing
+  static const double laneVerticalSpacing = 8.0;
+  static const double verticalOuterPadding = 16.0;
+
+  // Event pill appearance
+  static const double pillBorderRadius = 4.0;
+  static const EdgeInsets pillPadding = EdgeInsets.symmetric(
+    horizontal: 8.0,
+    vertical: 6.0,
+  );
+
+  // Content width
+  static const double minContentWidth = 1200.0;
+}

packages/z-timeline/lib/src/models/entry_drag_state.dart

@@ -0,0 +1,83 @@
+import 'package:flutter/foundation.dart';
+
+import 'timeline_entry.dart';
+
+/// Immutable state tracking during drag operations.
+///
+/// Captures the entry being dragged and its target position.
+@immutable
+class EntryDragState {
+  const EntryDragState({
+    required this.entryId,
+    required this.originalEntry,
+    required this.targetGroupId,
+    required this.targetLane,
+    required this.targetStart,
+  });
+
+  /// The ID of the entry being dragged.
+  final String entryId;
+
+  /// The original entry (for duration calculation).
+  final TimelineEntry originalEntry;
+
+  /// The target group ID.
+  final String targetGroupId;
+
+  /// The target lane (resolved to avoid conflicts).
+  final int targetLane;
+
+  /// The target start time.
+  final DateTime targetStart;
+
+  /// Calculate target end preserving the original duration.
+  DateTime get targetEnd =>
+      targetStart.add(originalEntry.end.difference(originalEntry.start));
+
+  /// The duration of the entry.
+  Duration get duration => originalEntry.end.difference(originalEntry.start);
+
+  EntryDragState copyWith({
+    String? entryId,
+    TimelineEntry? originalEntry,
+    String? targetGroupId,
+    int? targetLane,
+    DateTime? targetStart,
+  }) {
+    return EntryDragState(
+      entryId: entryId ?? this.entryId,
+      originalEntry: originalEntry ?? this.originalEntry,
+      targetGroupId: targetGroupId ?? this.targetGroupId,
+      targetLane: targetLane ?? this.targetLane,
+      targetStart: targetStart ?? this.targetStart,
+    );
+  }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    return other is EntryDragState &&
+        other.entryId == entryId &&
+        other.originalEntry == originalEntry &&
+        other.targetGroupId == targetGroupId &&
+        other.targetLane == targetLane &&
+        other.targetStart == targetStart;
+  }
+
+  @override
+  int get hashCode => Object.hash(
+    entryId,
+    originalEntry,
+    targetGroupId,
+    targetLane,
+    targetStart,
+  );
+
+  @override
+  String toString() =>
+      'EntryDragState('
+      'entryId: $entryId, '
+      'targetGroupId: $targetGroupId, '
+      'targetLane: $targetLane, '
+      'targetStart: $targetStart)';
+}

packages/z-timeline/lib/src/models/interaction_config.dart

@@ -0,0 +1,102 @@
+import 'package:flutter/foundation.dart';
+
+/// Configuration for timeline pan/zoom interactions.
+@immutable
+class ZTimelineInteractionConfig {
+  const ZTimelineInteractionConfig({
+    this.zoomFactorIn = 1.1,
+    this.zoomFactorOut = 0.9,
+    this.keyboardPanRatio = 0.1,
+    this.enablePinchZoom = true,
+    this.enableMouseWheelZoom = true,
+    this.enablePan = true,
+    this.enableKeyboardShortcuts = true,
+    this.minZoomDuration = const Duration(hours: 1),
+    this.maxZoomDuration = const Duration(days: 3650),
+  });
+
+  /// Zoom factor applied when zooming in (> 1.0 zooms in, reduces duration).
+  final double zoomFactorIn;
+
+  /// Zoom factor applied when zooming out (< 1.0 zooms out, increases duration).
+  final double zoomFactorOut;
+
+  /// Pan ratio for keyboard arrow keys (fraction of visible domain).
+  final double keyboardPanRatio;
+
+  /// Enable two-finger pinch-to-zoom gesture.
+  final bool enablePinchZoom;
+
+  /// Enable Ctrl/Cmd + mouse wheel zoom.
+  final bool enableMouseWheelZoom;
+
+  /// Enable single-finger/mouse drag panning.
+  final bool enablePan;
+
+  /// Enable keyboard shortcuts (arrows for pan, +/- for zoom).
+  final bool enableKeyboardShortcuts;
+
+  /// Minimum domain duration (prevents zooming in too far).
+  final Duration minZoomDuration;
+
+  /// Maximum domain duration (prevents zooming out too far).
+  final Duration maxZoomDuration;
+
+  /// Default configuration.
+  static const defaults = ZTimelineInteractionConfig();
+
+  ZTimelineInteractionConfig copyWith({
+    double? zoomFactorIn,
+    double? zoomFactorOut,
+    double? keyboardPanRatio,
+    bool? enablePinchZoom,
+    bool? enableMouseWheelZoom,
+    bool? enablePan,
+    bool? enableKeyboardShortcuts,
+    Duration? minZoomDuration,
+    Duration? maxZoomDuration,
+  }) {
+    return ZTimelineInteractionConfig(
+      zoomFactorIn: zoomFactorIn ?? this.zoomFactorIn,
+      zoomFactorOut: zoomFactorOut ?? this.zoomFactorOut,
+      keyboardPanRatio: keyboardPanRatio ?? this.keyboardPanRatio,
+      enablePinchZoom: enablePinchZoom ?? this.enablePinchZoom,
+      enableMouseWheelZoom: enableMouseWheelZoom ?? this.enableMouseWheelZoom,
+      enablePan: enablePan ?? this.enablePan,
+      enableKeyboardShortcuts:
+          enableKeyboardShortcuts ?? this.enableKeyboardShortcuts,
+      minZoomDuration: minZoomDuration ?? this.minZoomDuration,
+      maxZoomDuration: maxZoomDuration ?? this.maxZoomDuration,
+    );
+  }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    return other is ZTimelineInteractionConfig &&
+        other.zoomFactorIn == zoomFactorIn &&
+        other.zoomFactorOut == zoomFactorOut &&
+        other.keyboardPanRatio == keyboardPanRatio &&
+        other.enablePinchZoom == enablePinchZoom &&
+        other.enableMouseWheelZoom == enableMouseWheelZoom &&
+        other.enablePan == enablePan &&
+        other.enableKeyboardShortcuts == enableKeyboardShortcuts &&
+        other.minZoomDuration == minZoomDuration &&
+        other.maxZoomDuration == maxZoomDuration;
+  }
+
+  @override
+  int get hashCode {
+    return Object.hash(
+      zoomFactorIn,
+      zoomFactorOut,
+      keyboardPanRatio,
+      enablePinchZoom,
+      enableMouseWheelZoom,
+      enablePan,
+      enableKeyboardShortcuts,
+      minZoomDuration,
+      maxZoomDuration,
+    );
+  }
+}

packages/z-timeline/lib/src/models/interaction_state.dart

@@ -0,0 +1,41 @@
+import 'package:flutter/foundation.dart';
+
+/// Transient state for timeline interactions.
+///
+/// This is separate from viewport state as it represents UI feedback state,
+/// not the actual domain/data state.
+@immutable
+class ZTimelineInteractionState {
+  const ZTimelineInteractionState({
+    this.isGrabbing = false,
+    this.isDraggingEntry = false,
+  });
+
+  /// Whether the user is actively panning (for cursor feedback).
+  final bool isGrabbing;
+
+  /// Whether an entry is being dragged (disables pan gesture).
+  /// This will be used by future drag-and-drop functionality.
+  final bool isDraggingEntry;
+
+  ZTimelineInteractionState copyWith({
+    bool? isGrabbing,
+    bool? isDraggingEntry,
+  }) {
+    return ZTimelineInteractionState(
+      isGrabbing: isGrabbing ?? this.isGrabbing,
+      isDraggingEntry: isDraggingEntry ?? this.isDraggingEntry,
+    );
+  }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    return other is ZTimelineInteractionState &&
+        other.isGrabbing == isGrabbing &&
+        other.isDraggingEntry == isDraggingEntry;
+  }
+
+  @override
+  int get hashCode => Object.hash(isGrabbing, isDraggingEntry);
+}

packages/z-timeline/lib/src/models/projected_entry.dart

@@ -0,0 +1,37 @@
+import 'package:flutter/foundation.dart';
+import 'timeline_entry.dart';
+
+/// Represents a projected entry on the timeline.
+/// This is used to represent an entry on the timeline in a normalized space.
+/// The startX and endX are normalized in [0, 1] and represent the position of
+/// the entry on the timeline.
+/// The widthX is the width of the entry in the normalized space.
+@immutable
+class ProjectedEntry {
+  const ProjectedEntry({
+    required this.entry,
+    required this.startX,
+    required this.endX,
+  }) : assert(startX <= endX, 'Projected startX must be <= endX');
+
+  final TimelineEntry entry;
+  final double startX; // normalized in [0, 1]
+  final double endX; // normalized in [0, 1]
+
+  double get widthX => (endX - startX).clamp(0.0, 1.0);
+
+  @override
+  int get hashCode => Object.hash(entry, startX, endX);
+
+  @override
+  bool operator ==(Object other) {
+    return other is ProjectedEntry &&
+        other.entry == entry &&
+        other.startX == startX &&
+        other.endX == endX;
+  }
+
+  @override
+  String toString() =>
+      'ProjectedEntry(entry: ${entry.id}, startX: $startX, endX: $endX)';
+}

packages/z-timeline/lib/src/models/timeline_entry.dart

@@ -0,0 +1,55 @@
+import 'package:flutter/foundation.dart';
+
+@immutable
+class TimelineEntry {
+  TimelineEntry({
+    required this.id,
+    required this.groupId,
+    required this.start,
+    required this.end,
+    required this.lane,
+  }) : assert(!end.isBefore(start), 'Entry end must be on/after start');
+
+  final String id;
+  final String groupId;
+  final DateTime start;
+  final DateTime end;
+  final int lane; // provided by consumer for stacking
+
+  bool overlaps(DateTime a, DateTime b) {
+    return !(end.isBefore(a) || start.isAfter(b));
+  }
+
+  TimelineEntry copyWith({
+    String? id,
+    String? groupId,
+    DateTime? start,
+    DateTime? end,
+    int? lane,
+  }) {
+    return TimelineEntry(
+      id: id ?? this.id,
+      groupId: groupId ?? this.groupId,
+      start: start ?? this.start,
+      end: end ?? this.end,
+      lane: lane ?? this.lane,
+    );
+  }
+
+  @override
+  int get hashCode => Object.hash(id, groupId, start, end, lane);
+
+  @override
+  bool operator ==(Object other) {
+    return other is TimelineEntry &&
+        other.id == id &&
+        other.groupId == groupId &&
+        other.start == start &&
+        other.end == end &&
+        other.lane == lane;
+  }
+
+  @override
+  String toString() =>
+      'TimelineEntry(id: $id, groupId: $groupId, start: $start, end: $end, lane: $lane)';
+}

packages/z-timeline/lib/src/models/timeline_group.dart

@@ -0,0 +1,24 @@
+import 'package:flutter/foundation.dart';
+
+@immutable
+class TimelineGroup {
+  const TimelineGroup({required this.id, required this.title});
+
+  final String id;
+  final String title;
+
+  TimelineGroup copyWith({String? id, String? title}) {
+    return TimelineGroup(id: id ?? this.id, title: title ?? this.title);
+  }
+
+  @override
+  int get hashCode => Object.hash(id, title);
+
+  @override
+  bool operator ==(Object other) {
+    return other is TimelineGroup && other.id == id && other.title == title;
+  }
+
+  @override
+  String toString() => 'TimelineGroup(id: $id, title: $title)';
+}

packages/z-timeline/lib/src/services/entry_placement_service.dart

@@ -0,0 +1,168 @@
+import 'package:flutter/foundation.dart';
+
+import '../models/timeline_entry.dart';
+
+/// Result of resolving placement for an entry.
+@immutable
+class ResolvedPlacement {
+  const ResolvedPlacement({required this.lane, required this.end});
+
+  /// The resolved lane (collision-free).
+  final int lane;
+
+  /// The calculated end time (preserving duration).
+  final DateTime end;
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    return other is ResolvedPlacement && other.lane == lane && other.end == end;
+  }
+
+  @override
+  int get hashCode => Object.hash(lane, end);
+
+  @override
+  String toString() => 'ResolvedPlacement(lane: $lane, end: $end)';
+}
+
+/// Pure utility for entry placement validation and resolution.
+///
+/// Handles collision detection and lane assignment for drag-and-drop
+/// operations.
+class EntryPlacementService {
+  const EntryPlacementService._();
+
+  /// Check if a position is available for an entry.
+  ///
+  /// Returns true if no other entries occupy the same lane and time range.
+  /// The entry being dragged (identified by [entryId]) is excluded from
+  /// collision detection.
+  static bool isPositionAvailable({
+    required String entryId,
+    required String targetGroupId,
+    required int targetLane,
+    required DateTime targetStart,
+    required DateTime targetEnd,
+    required List<TimelineEntry> existingEntries,
+  }) {
+    // Filter entries in target group and lane, excluding dragged entry
+    final conflicting = existingEntries.where(
+      (e) =>
+          e.id != entryId && e.groupId == targetGroupId && e.lane == targetLane,
+    );
+
+    // Check for time overlaps
+    for (final existing in conflicting) {
+      if (_entriesOverlap(
+        targetStart,
+        targetEnd,
+        existing.start,
+        existing.end,
+      )) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /// Find the nearest available lane from target.
+  ///
+  /// Returns the target lane if available, otherwise searches in expanding
+  /// radius: target, target+1, target-1, target+2, target-2, etc.
+  static int findNearestAvailableLane({
+    required String entryId,
+    required String targetGroupId,
+    required int targetLane,
+    required DateTime targetStart,
+    required DateTime targetEnd,
+    required List<TimelineEntry> existingEntries,
+  }) {
+    // Check target lane first
+    if (isPositionAvailable(
+      entryId: entryId,
+      targetGroupId: targetGroupId,
+      targetLane: targetLane,
+      targetStart: targetStart,
+      targetEnd: targetEnd,
+      existingEntries: existingEntries,
+    )) {
+      return targetLane;
+    }
+
+    // Search in expanding radius: +1, -1, +2, -2, ...
+    var offset = 1;
+    while (offset <= 100) {
+      // Try lane above
+      final upperLane = targetLane + offset;
+      if (isPositionAvailable(
+        entryId: entryId,
+        targetGroupId: targetGroupId,
+        targetLane: upperLane,
+        targetStart: targetStart,
+        targetEnd: targetEnd,
+        existingEntries: existingEntries,
+      )) {
+        return upperLane;
+      }
+
+      // Try lane below (if valid)
+      final lowerLane = targetLane - offset;
+      if (lowerLane >= 1 &&
+          isPositionAvailable(
+            entryId: entryId,
+            targetGroupId: targetGroupId,
+            targetLane: lowerLane,
+            targetStart: targetStart,
+            targetEnd: targetEnd,
+            existingEntries: existingEntries,
+          )) {
+        return lowerLane;
+      }
+
+      offset++;
+    }
+
+    // Fallback: new lane above all existing
+    final maxLane = existingEntries
+        .where((e) => e.groupId == targetGroupId)
+        .fold<int>(0, (max, e) => e.lane > max ? e.lane : max);
+    return maxLane + 1;
+  }
+
+  /// Resolve final placement with collision avoidance.
+  ///
+  /// Returns a [ResolvedPlacement] with the calculated lane (avoiding
+  /// collisions) and end time (preserving the original entry's duration).
+  static ResolvedPlacement resolvePlacement({
+    required TimelineEntry entry,
+    required String targetGroupId,
+    required int targetLane,
+    required DateTime targetStart,
+    required List<TimelineEntry> existingEntries,
+  }) {
+    final duration = entry.end.difference(entry.start);
+    final targetEnd = targetStart.add(duration);
+
+    final lane = findNearestAvailableLane(
+      entryId: entry.id,
+      targetGroupId: targetGroupId,
+      targetLane: targetLane,
+      targetStart: targetStart,
+      targetEnd: targetEnd,
+      existingEntries: existingEntries,
+    );
+
+    return ResolvedPlacement(lane: lane, end: targetEnd);
+  }
+
+  /// Check if two time ranges overlap.
+  static bool _entriesOverlap(
+    DateTime s1,
+    DateTime e1,
+    DateTime s2,
+    DateTime e2,
+  ) {
+    return s1.isBefore(e2) && e1.isAfter(s2);
+  }
+}

packages/z-timeline/lib/src/services/layout_coordinate_service.dart

@@ -0,0 +1,96 @@
+import '../constants.dart';
+
+/// Handles ALL coordinate transformations for timeline layout.
+///
+/// This service centralizes position calculations to ensure consistency
+/// between different components (pills, ghost overlays, drop targets).
+///
+/// ## Coordinate Spaces
+///
+/// The timeline uses two coordinate spaces:
+///
+/// 1. **Normalized** `[0.0, 1.0]`: Position relative to the time domain.
+///    Used by [TimeScaleService] and stored in [ProjectedEntry].
+///
+/// 2. **Widget** `[0.0, contentWidth]`: Pixel space inside the timeline.
+///    What gets passed to [Positioned] widgets.
+///
+/// All positioned elements (pills, ghost overlay, drop targets) share the
+/// same coordinate space inside the Padding widget.
+class LayoutCoordinateService {
+  const LayoutCoordinateService._();
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Width Calculations
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /// Calculate item width (pill or ghost) from normalized width.
+  ///
+  /// This is the CANONICAL width calculation. Both pills and ghosts use this
+  /// to ensure they have identical widths.
+  ///
+  /// The horizontal padding is subtracted to create visual spacing between
+  /// adjacent items.
+  static double calculateItemWidth({
+    required double normalizedWidth,
+    required double contentWidth,
+  }) {
+    return (normalizedWidth * contentWidth)
+        .clamp(0.0, double.infinity);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Horizontal Position Transformations
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /// Convert normalized X position to widget X coordinate.
+  ///
+  /// Adds horizontal padding to create left margin for items.
+  /// Used by both pills and ghost overlay for left positioning.
+  static double normalizedToWidgetX({
+    required double normalizedX,
+    required double contentWidth,
+  }) {
+    return normalizedX * contentWidth;
+  }
+
+  /// Convert widget X coordinate to normalized position.
+  ///
+  /// Used by drop targets to convert cursor position back to normalized
+  /// space for time calculation.
+  static double widgetXToNormalized({
+    required double widgetX,
+    required double contentWidth,
+  }) {
+    final adjustedX =
+        (widgetX).clamp(0.0, contentWidth);
+    return contentWidth == 0 ? 0.0 : adjustedX / contentWidth;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Vertical Position Transformations
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /// Calculate Y position for a lane.
+  ///
+  /// Used by all positioned elements (pills, ghost overlay) within the
+  /// timeline Stack. Lanes are 1-indexed, so lane 1 starts at Y=0.
+  static double laneToY({
+    required int lane,
+    required double laneHeight,
+  }) {
+    return (lane - 1) * (laneHeight + ZTimelineConstants.laneVerticalSpacing);
+  }
+
+  /// Convert Y coordinate to lane number.
+  ///
+  /// Used by drop targets to determine which lane the cursor is over.
+  /// The Y coordinate should be relative to the timeline Stack.
+  static int yToLane({
+    required double y,
+    required double laneHeight,
+  }) {
+    final laneStep = laneHeight + ZTimelineConstants.laneVerticalSpacing;
+    return (y / laneStep).floor() + 1;
+  }
+}

packages/z-timeline/lib/src/services/time_scale_service.dart

@@ -0,0 +1,78 @@
+class TimeScaleService {
+  const TimeScaleService._();
+
+  /// Maps a time to a position in the domain.
+  /// The result is a value between 0.0 and 1.0 and it is the relative position
+  /// of the time in the domain.
+  static double mapTimeToPosition(
+    DateTime time,
+    DateTime domainStart,
+    DateTime domainEnd,
+  ) {
+    final timeMs = time.millisecondsSinceEpoch.toDouble();
+    final startMs = domainStart.millisecondsSinceEpoch.toDouble();
+    final endMs = domainEnd.millisecondsSinceEpoch.toDouble();
+    return (timeMs - startMs) / (endMs - startMs);
+  }
+
+  /// Maps a position in the domain to a time.
+  /// The result is a DateTime value and it is the time corresponding to the
+  /// position in the domain.
+  static DateTime mapPositionToTime(
+    double position,
+    DateTime domainStart,
+    DateTime domainEnd,
+  ) {
+    final startMs = domainStart.millisecondsSinceEpoch.toDouble();
+    final endMs = domainEnd.millisecondsSinceEpoch.toDouble();
+    final timeMs = startMs + position * (endMs - startMs);
+    return DateTime.fromMillisecondsSinceEpoch(timeMs.round());
+  }
+
+  /// Calculates the duration of the domain in milliseconds.
+  static double domainDuration(DateTime domainStart, DateTime domainEnd) {
+    return (domainEnd.millisecondsSinceEpoch -
+            domainStart.millisecondsSinceEpoch)
+        .toDouble();
+  }
+
+  /// Calculates a new domain after applying a zoom operation.
+  /// The result is a record with the new (start, end) domain.
+  static ({DateTime start, DateTime end}) calculateZoomedDomain(
+    DateTime domainStart,
+    DateTime domainEnd, {
+    required double factor,
+    double focusPosition = 0.5,
+  }) {
+    final oldDuration = domainDuration(domainStart, domainEnd);
+    final newDuration = oldDuration / factor;
+    final focusTime = mapPositionToTime(focusPosition, domainStart, domainEnd);
+    final newStartOffset = focusPosition * newDuration;
+    final newStart = DateTime.fromMillisecondsSinceEpoch(
+      (focusTime.millisecondsSinceEpoch - newStartOffset).round(),
+    );
+    final newEnd = DateTime.fromMillisecondsSinceEpoch(
+      (focusTime.millisecondsSinceEpoch + (newDuration - newStartOffset))
+          .round(),
+    );
+    return (start: newStart, end: newEnd);
+  }
+
+  /// Calculates a new domain after applying a pan operation.
+  /// The result is a record with the new (start, end) domain.
+  static ({DateTime start, DateTime end}) calculatePannedDomain(
+    DateTime domainStart,
+    DateTime domainEnd, {
+    required double ratio,
+  }) {
+    final shiftAmount = domainDuration(domainStart, domainEnd) * ratio;
+    final shiftMs = shiftAmount.round();
+    final newStart = DateTime.fromMillisecondsSinceEpoch(
+      domainStart.millisecondsSinceEpoch + shiftMs,
+    );
+    final newEnd = DateTime.fromMillisecondsSinceEpoch(
+      domainEnd.millisecondsSinceEpoch + shiftMs,
+    );
+    return (start: newStart, end: newEnd);
+  }
+}

packages/z-timeline/lib/src/services/time_tick_builder.dart

@@ -0,0 +1,124 @@
+class TimeInterval {
+  const TimeInterval(this.unit, this.step, this.approx);
+  final TimeUnit unit;
+  final int step;
+  final Duration approx;
+
+  DateTime floor(DateTime d) {
+    switch (unit) {
+      case TimeUnit.second:
+        return DateTime.utc(
+          d.year,
+          d.month,
+          d.day,
+          d.hour,
+          d.minute,
+          (d.second ~/ step) * step,
+        );
+      case TimeUnit.minute:
+        return DateTime.utc(
+          d.year,
+          d.month,
+          d.day,
+          d.hour,
+          (d.minute ~/ step) * step,
+        );
+      case TimeUnit.hour:
+        return DateTime.utc(d.year, d.month, d.day, (d.hour ~/ step) * step);
+      case TimeUnit.day:
+        return DateTime.utc(d.year, d.month, (d.day - 1) ~/ step * step + 1);
+      case TimeUnit.week:
+        final monday = d.subtract(Duration(days: d.weekday - 1));
+        return DateTime.utc(
+          monday.year,
+          monday.month,
+          monday.day,
+        ).subtract(Duration(days: 0 % step));
+      case TimeUnit.month:
+        return DateTime.utc(d.year, ((d.month - 1) ~/ step) * step + 1);
+      case TimeUnit.year:
+        return DateTime.utc((d.year ~/ step) * step);
+    }
+  }
+
+  DateTime addTo(DateTime d) {
+    switch (unit) {
+      case TimeUnit.second:
+        return d.add(Duration(seconds: step));
+      case TimeUnit.minute:
+        return d.add(Duration(minutes: step));
+      case TimeUnit.hour:
+        return d.add(Duration(hours: step));
+      case TimeUnit.day:
+        return d.add(Duration(days: step));
+      case TimeUnit.week:
+        return d.add(Duration(days: 7 * step));
+      case TimeUnit.month:
+        return DateTime.utc(d.year, d.month + step, d.day);
+      case TimeUnit.year:
+        return DateTime.utc(d.year + step, d.month, d.day);
+    }
+  }
+}
+
+enum TimeUnit { second, minute, hour, day, week, month, year }
+
+class TickConfig {
+  const TickConfig({
+    this.minPixelsPerTick = 60,
+    this.candidates = _defaultIntervals,
+  });
+  final double minPixelsPerTick;
+  final List<TimeInterval> candidates;
+}
+
+List<DateTime> dateTicks({
+  required DateTime start,
+  required DateTime end,
+  required double widthPx,
+  TickConfig config = const TickConfig(),
+}) {
+  assert(!end.isBefore(start), 'End date must not be before start date');
+  final spanMs = end.difference(start).inMilliseconds;
+  final msPerPixel = spanMs / widthPx;
+
+  var chosen = config.candidates.last;
+  for (final i in config.candidates) {
+    final pixels = i.approx.inMilliseconds / msPerPixel;
+    if (pixels >= config.minPixelsPerTick) {
+      chosen = i;
+      break;
+    }
+  }
+
+  final ticks = <DateTime>[];
+  var t = chosen.floor(start);
+  while (!t.isAfter(end)) {
+    ticks.add(t);
+    t = chosen.addTo(t);
+  }
+  return ticks;
+}
+
+const _defaultIntervals = <TimeInterval>[
+  TimeInterval(TimeUnit.second, 1, Duration(seconds: 1)),
+  TimeInterval(TimeUnit.second, 5, Duration(seconds: 5)),
+  TimeInterval(TimeUnit.second, 15, Duration(seconds: 15)),
+  TimeInterval(TimeUnit.second, 30, Duration(seconds: 30)),
+  TimeInterval(TimeUnit.minute, 1, Duration(minutes: 1)),
+  TimeInterval(TimeUnit.minute, 5, Duration(minutes: 5)),
+  TimeInterval(TimeUnit.minute, 15, Duration(minutes: 15)),
+  TimeInterval(TimeUnit.minute, 30, Duration(minutes: 30)),
+  TimeInterval(TimeUnit.hour, 1, Duration(hours: 1)),
+  TimeInterval(TimeUnit.hour, 3, Duration(hours: 3)),
+  TimeInterval(TimeUnit.hour, 6, Duration(hours: 6)),
+  TimeInterval(TimeUnit.hour, 12, Duration(hours: 12)),
+  TimeInterval(TimeUnit.day, 1, Duration(days: 1)),
+  TimeInterval(TimeUnit.day, 7, Duration(days: 7)),
+  TimeInterval(TimeUnit.month, 1, Duration(days: 30)),
+  TimeInterval(TimeUnit.month, 3, Duration(days: 90)),
+  TimeInterval(TimeUnit.month, 6, Duration(days: 180)),
+  TimeInterval(TimeUnit.year, 1, Duration(days: 365)),
+  TimeInterval(TimeUnit.year, 5, Duration(days: 365 * 5)),
+  TimeInterval(TimeUnit.year, 10, Duration(days: 365 * 10)),
+];

packages/z-timeline/lib/src/services/timeline_projection_service.dart

@@ -0,0 +1,42 @@
+import '../models/timeline_entry.dart';
+import '../models/projected_entry.dart';
+import 'time_scale_service.dart';
+
+class TimelineProjectionService {
+  const TimelineProjectionService();
+
+  Map<String, List<ProjectedEntry>> project({
+    required Iterable<TimelineEntry> entries,
+    required DateTime domainStart,
+    required DateTime domainEnd,
+  }) {
+    final byGroup = <String, List<ProjectedEntry>>{};
+    for (final e in entries) {
+      if (e.overlaps(domainStart, domainEnd)) {
+        final startX = TimeScaleService.mapTimeToPosition(
+          e.start.isBefore(domainStart) ? domainStart : e.start,
+          domainStart,
+          domainEnd,
+        ).clamp(0.0, 1.0);
+        final endX = TimeScaleService.mapTimeToPosition(
+          e.end.isAfter(domainEnd) ? domainEnd : e.end,
+          domainStart,
+          domainEnd,
+        ).clamp(0.0, 1.0);
+
+        final pe = ProjectedEntry(entry: e, startX: startX, endX: endX);
+        (byGroup[e.groupId] ??= <ProjectedEntry>[]).add(pe);
+      }
+    }
+
+    // Keep original order stable by lane then startX
+    for (final list in byGroup.values) {
+      list.sort((a, b) {
+        final laneCmp = a.entry.lane.compareTo(b.entry.lane);
+        if (laneCmp != 0) return laneCmp;
+        return a.startX.compareTo(b.startX);
+      });
+    }
+    return byGroup;
+  }
+}

packages/z-timeline/lib/src/state/timeline_interaction_notifier.dart

@@ -0,0 +1,92 @@
+import 'package:flutter/foundation.dart';
+
+import '../models/entry_drag_state.dart';
+import '../models/interaction_state.dart';
+import '../models/timeline_entry.dart';
+
+/// Notifier for transient interaction state.
+///
+/// Separate from viewport to handle UI feedback state like cursor changes
+/// and drag-drop coordination.
+class ZTimelineInteractionNotifier extends ChangeNotifier {
+  ZTimelineInteractionNotifier();
+
+  ZTimelineInteractionState _state = const ZTimelineInteractionState();
+  EntryDragState? _dragState;
+
+  /// The current interaction state.
+  ZTimelineInteractionState get state => _state;
+
+  /// The current drag state, or null if no drag is active.
+  EntryDragState? get dragState => _dragState;
+
+  /// Whether the user is actively panning (for cursor feedback).
+  bool get isGrabbing => _state.isGrabbing;
+
+  /// Whether an entry is being dragged (disables pan gesture).
+  bool get isDraggingEntry => _state.isDraggingEntry;
+
+  /// Update the grabbing state.
+  void setGrabbing(bool value) {
+    if (_state.isGrabbing == value) return;
+    _state = _state.copyWith(isGrabbing: value);
+    notifyListeners();
+  }
+
+  /// Update the dragging entry state.
+  void setDraggingEntry(bool value) {
+    if (_state.isDraggingEntry == value) return;
+    _state = _state.copyWith(isDraggingEntry: value);
+    notifyListeners();
+  }
+
+  /// Begin dragging an entry.
+  ///
+  /// Sets drag state and marks [isDraggingEntry] as true.
+  void beginDrag(TimelineEntry entry) {
+    _dragState = EntryDragState(
+      entryId: entry.id,
+      originalEntry: entry,
+      targetGroupId: entry.groupId,
+      targetLane: entry.lane,
+      targetStart: entry.start,
+    );
+    setDraggingEntry(true);
+  }
+
+  /// Update the drag target position.
+  ///
+  /// Called during drag to update where the entry would land.
+  void updateDragTarget({
+    required String targetGroupId,
+    required int targetLane,
+    required DateTime targetStart,
+  }) {
+    if (_dragState == null) return;
+    final newState = _dragState!.copyWith(
+      targetGroupId: targetGroupId,
+      targetLane: targetLane,
+      targetStart: targetStart,
+    );
+    if (newState == _dragState) return;
+    _dragState = newState;
+    notifyListeners();
+  }
+
+  /// End the drag and clear state.
+  void endDrag() {
+    _dragState = null;
+    setDraggingEntry(false);
+  }
+
+  /// Cancel the drag (alias for [endDrag]).
+  void cancelDrag() => endDrag();
+
+  /// Called by drag-drop system when an entry drag starts.
+  @Deprecated('Use beginDrag instead')
+  void beginEntryDrag() => setDraggingEntry(true);
+
+  /// Called by drag-drop system when an entry drag ends.
+  @Deprecated('Use endDrag instead')
+  void endEntryDrag() => setDraggingEntry(false);
+}

packages/z-timeline/lib/src/state/timeline_viewport_notifier.dart

@@ -0,0 +1,48 @@
+import 'package:flutter/foundation.dart';
+import '../services/time_scale_service.dart';
+
+class TimelineViewportNotifier extends ChangeNotifier {
+  TimelineViewportNotifier({required DateTime start, required DateTime end})
+    : assert(start.isBefore(end), 'Viewport start must be before end'),
+      _start = start,
+      _end = end;
+
+  DateTime _start;
+  DateTime _end;
+
+  DateTime get start => _start;
+  DateTime get end => _end;
+
+  void setDomain(DateTime start, DateTime end) {
+    if (!start.isBefore(end)) return;
+    if (start == _start && end == _end) return;
+    _start = start;
+    _end = end;
+    notifyListeners();
+  }
+
+  void zoom(double factor, {double focusPosition = 0.5}) {
+    final next = TimeScaleService.calculateZoomedDomain(
+      _start,
+      _end,
+      factor: factor,
+      focusPosition: focusPosition,
+    );
+    if (!next.start.isBefore(next.end)) return;
+    _start = next.start;
+    _end = next.end;
+    notifyListeners();
+  }
+
+  void pan(double ratio) {
+    final next = TimeScaleService.calculatePannedDomain(
+      _start,
+      _end,
+      ratio: ratio,
+    );
+    if (!next.start.isBefore(next.end)) return;
+    _start = next.start;
+    _end = next.end;
+    notifyListeners();
+  }
+}

packages/z-timeline/lib/src/widgets/draggable_event_pill.dart

@@ -0,0 +1,122 @@
+import 'package:flutter/material.dart';
+
+import '../constants.dart';
+import '../models/projected_entry.dart';
+import '../models/timeline_entry.dart';
+import '../services/layout_coordinate_service.dart';
+import 'timeline_scope.dart';
+import 'timeline_view.dart';
+
+/// A draggable event pill widget.
+///
+/// Renders a timeline entry as a pill that can be dragged to move it
+/// to a new position. Uses Flutter's built-in [Draggable] widget.
+class DraggableEventPill extends StatelessWidget {
+  const DraggableEventPill({
+    required this.entry,
+    required this.laneHeight,
+    required this.labelBuilder,
+    required this.colorBuilder,
+    required this.contentWidth,
+    required this.enableDrag,
+    super.key,
+  });
+
+  final ProjectedEntry entry;
+  final double laneHeight;
+  final EntryLabelBuilder labelBuilder;
+  final EntryColorBuilder colorBuilder;
+  final double contentWidth;
+  final bool enableDrag;
+
+  @override
+  Widget build(BuildContext context) {
+    final pill = _buildPill(context);
+
+    // Use centralized coordinate service for consistent positioning
+    final top = LayoutCoordinateService.laneToY(
+      lane: entry.entry.lane,
+      laneHeight: laneHeight,
+    );
+    final left = LayoutCoordinateService.normalizedToWidgetX(
+      normalizedX: entry.startX,
+      contentWidth: contentWidth,
+    );
+    final width = LayoutCoordinateService.calculateItemWidth(
+      normalizedWidth: entry.widthX,
+      contentWidth: contentWidth,
+    );
+
+    if (!enableDrag) {
+      return Positioned(
+        top: top,
+        left: left.clamp(0.0, double.infinity),
+        width: width.clamp(0.0, double.infinity),
+        height: laneHeight,
+        child: pill,
+      );
+    }
+
+    final scope = ZTimelineScope.of(context);
+
+    return Positioned(
+      top: top,
+      left: left.clamp(0.0, double.infinity),
+      width: width.clamp(0.0, double.infinity),
+      height: laneHeight,
+      child: Draggable<TimelineEntry>(
+        data: entry.entry,
+        onDragStarted: () {
+          scope.interaction.beginDrag(entry.entry);
+        },
+        onDraggableCanceled: (_, _) {
+          scope.interaction.cancelDrag();
+        },
+        onDragCompleted: () {
+          // Handled by DragTarget
+        },
+        feedback: DefaultTextStyle(
+          style: Theme.of(context).textTheme.labelMedium ?? const TextStyle(),
+          child: Opacity(
+            opacity: 0.8,
+            child: SizedBox(
+              width: width.clamp(0.0, double.infinity),
+              height: laneHeight,
+              child: pill,
+            ),
+          ),
+        ),
+        childWhenDragging: Opacity(opacity: 0.3, child: pill),
+        child: pill,
+      ),
+    );
+  }
+
+  Widget _buildPill(BuildContext context) {
+    final color = colorBuilder(entry.entry);
+    final onColor =
+        ThemeData.estimateBrightnessForColor(color) == Brightness.dark
+        ? Colors.white
+        : Colors.black87;
+
+    return Container(
+      padding: ZTimelineConstants.pillPadding,
+      decoration: BoxDecoration(
+        color: color,
+        borderRadius: BorderRadius.circular(
+          ZTimelineConstants.pillBorderRadius,
+        ),
+      ),
+      alignment: Alignment.centerLeft,
+      child: Text(
+        labelBuilder(entry.entry),
+        maxLines: 1,
+        overflow: TextOverflow.ellipsis,
+        style: Theme.of(context).textTheme.labelMedium?.copyWith(
+          color: onColor,
+          fontWeight: FontWeight.w400,
+        ),
+      ),
+    );
+  }
+}

packages/z-timeline/lib/src/widgets/ghost_overlay.dart

@@ -0,0 +1,77 @@
+import 'package:flutter/material.dart';
+
+import '../constants.dart';
+import '../models/entry_drag_state.dart';
+import '../services/layout_coordinate_service.dart';
+import '../services/time_scale_service.dart';
+import '../state/timeline_viewport_notifier.dart';
+
+/// A semi-transparent ghost overlay showing where an entry will land.
+///
+/// Displayed during drag operations to give visual feedback about the
+/// target position.
+class GhostOverlay extends StatelessWidget {
+  const GhostOverlay({
+    required this.dragState,
+    required this.viewport,
+    required this.contentWidth,
+    required this.laneHeight,
+    super.key,
+  });
+
+  final EntryDragState dragState;
+  final TimelineViewportNotifier viewport;
+  final double contentWidth;
+  final double laneHeight;
+
+  @override
+  Widget build(BuildContext context) {
+    final startX = TimeScaleService.mapTimeToPosition(
+      dragState.targetStart,
+      viewport.start,
+      viewport.end,
+    );
+    final endX = TimeScaleService.mapTimeToPosition(
+      dragState.targetEnd,
+      viewport.start,
+      viewport.end,
+    );
+
+    // Use centralized coordinate service to ensure ghost matches pill layout
+    final left = LayoutCoordinateService.normalizedToWidgetX(
+      normalizedX: startX,
+      contentWidth: contentWidth,
+    );
+    final width = LayoutCoordinateService.calculateItemWidth(
+      normalizedWidth: endX - startX,
+      contentWidth: contentWidth,
+    );
+    final top = LayoutCoordinateService.laneToY(
+      lane: dragState.targetLane,
+      laneHeight: laneHeight,
+    );
+
+    final scheme = Theme.of(context).colorScheme;
+
+    return Positioned(
+      left: left.clamp(0.0, double.infinity),
+      width: width.clamp(0.0, double.infinity),
+      top: top,
+      height: laneHeight,
+      child: IgnorePointer(
+        child: Container(
+          decoration: BoxDecoration(
+            color: scheme.primary.withValues(alpha: 0.3),
+            borderRadius: BorderRadius.circular(
+              ZTimelineConstants.pillBorderRadius,
+            ),
+            border: Border.all(
+              color: scheme.primary.withValues(alpha: 0.6),
+              width: 2,
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}

packages/z-timeline/lib/src/widgets/group_drop_target.dart

@@ -0,0 +1,119 @@
+import 'package:flutter/material.dart';
+
+import '../models/projected_entry.dart';
+import '../models/timeline_entry.dart';
+import '../models/timeline_group.dart';
+import '../services/entry_placement_service.dart';
+import '../services/layout_coordinate_service.dart';
+import '../services/time_scale_service.dart';
+import '../state/timeline_viewport_notifier.dart';
+import 'timeline_scope.dart';
+import 'timeline_view.dart';
+
+/// A drop target wrapper for a timeline group.
+///
+/// Wraps group lanes content and handles drag-and-drop operations.
+/// The ghost overlay is rendered by the parent widget in the same Stack.
+class GroupDropTarget extends StatelessWidget {
+  const GroupDropTarget({
+    required this.group,
+    required this.entries,
+    required this.allEntries,
+    required this.viewport,
+    required this.contentWidth,
+    required this.laneHeight,
+    required this.lanesCount,
+    required this.onEntryMoved,
+    required this.child,
+    super.key,
+  });
+
+  final TimelineGroup group;
+  final List<ProjectedEntry> entries;
+  final List<TimelineEntry> allEntries;
+  final TimelineViewportNotifier viewport;
+  final double contentWidth;
+  final double laneHeight;
+  final int lanesCount;
+  final OnEntryMoved? onEntryMoved;
+  final Widget child;
+
+  @override
+  Widget build(BuildContext context) {
+    final scope = ZTimelineScope.of(context);
+
+    return DragTarget<TimelineEntry>(
+      builder: (context, candidateData, rejectedData) {
+        return child;
+      },
+      onWillAcceptWithDetails: (details) => true,
+      onMove: (details) {
+        final renderBox = context.findRenderObject() as RenderBox?;
+        if (renderBox == null) return;
+
+        final local = renderBox.globalToLocal(details.offset);
+
+        // Use centralized coordinate service for consistent transformations
+        final ratio = LayoutCoordinateService.widgetXToNormalized(
+          widgetX: local.dx,
+          contentWidth: contentWidth,
+        );
+
+        final targetStart = TimeScaleService.mapPositionToTime(
+          ratio,
+          viewport.start,
+          viewport.end,
+        );
+
+        final rawLane = LayoutCoordinateService.yToLane(
+          y: local.dy,
+          laneHeight: laneHeight,
+        );
+        final maxAllowedLane = (lanesCount <= 0 ? 1 : lanesCount) + 1;
+        final targetLane = rawLane.clamp(1, maxAllowedLane);
+
+        // Resolve with collision avoidance
+        final resolved = EntryPlacementService.resolvePlacement(
+          entry: details.data,
+          targetGroupId: group.id,
+          targetLane: targetLane,
+          targetStart: targetStart,
+          existingEntries: allEntries,
+        );
+
+        scope.interaction.updateDragTarget(
+          targetGroupId: group.id,
+          targetLane: resolved.lane,
+          targetStart: targetStart,
+        );
+      },
+      onAcceptWithDetails: (details) {
+        final dragState = scope.interaction.dragState;
+        if (dragState == null || onEntryMoved == null) {
+          scope.interaction.endDrag();
+          return;
+        }
+
+        final resolved = EntryPlacementService.resolvePlacement(
+          entry: details.data,
+          targetGroupId: dragState.targetGroupId,
+          targetLane: dragState.targetLane,
+          targetStart: dragState.targetStart,
+          existingEntries: allEntries,
+        );
+
+        onEntryMoved!(
+          details.data,
+          dragState.targetStart,
+          dragState.targetGroupId,
+          resolved.lane,
+        );
+
+        scope.interaction.endDrag();
+      },
+      onLeave: (data) {
+        // Don't clear on leave - entry might move to another group
+      },
+    );
+  }
+}

packages/z-timeline/lib/src/widgets/timeline_interactor.dart

@@ -0,0 +1,242 @@
+import 'package:flutter/gestures.dart'
+    show PointerScrollEvent, PointerSignalEvent;
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+
+import 'timeline_scope.dart';
+
+/// Handles pan/zoom gestures for the timeline.
+///
+/// Must be used within a [ZTimelineScope]. Supports:
+/// - Two-finger pinch-to-zoom (with focal point)
+/// - Single-finger horizontal pan
+/// - Ctrl/Cmd + mouse wheel zoom
+/// - Horizontal mouse scroll for pan
+/// - Keyboard shortcuts: arrows (pan), +/- (zoom)
+/// - Mouse cursor feedback (grab/grabbing)
+///
+/// ```dart
+/// ZTimelineScope(
+///   viewport: viewport,
+///   child: ZTimelineInteractor(
+///     child: ZTimelineView(...),
+///   ),
+/// )
+/// ```
+class ZTimelineInteractor extends StatefulWidget {
+  const ZTimelineInteractor({
+    required this.child,
+    this.autofocus = true,
+    super.key,
+  });
+
+  /// The widget to wrap with gesture handling.
+  final Widget child;
+
+  /// Whether to automatically focus this widget for keyboard input.
+  final bool autofocus;
+
+  @override
+  State<ZTimelineInteractor> createState() => _ZTimelineInteractorState();
+}
+
+class _ZTimelineInteractorState extends State<ZTimelineInteractor> {
+  double _prevScaleValue = 1.0;
+  Offset? _lastFocalPoint;
+  late FocusNode _focusNode;
+
+  @override
+  void initState() {
+    super.initState();
+    _focusNode = FocusNode();
+  }
+
+  @override
+  void dispose() {
+    _focusNode.dispose();
+    super.dispose();
+  }
+
+  double get _width {
+    final renderBox = context.findRenderObject() as RenderBox?;
+    return renderBox?.size.width ?? 1.0;
+  }
+
+  void _handleScaleStart(ScaleStartDetails details) {
+    _prevScaleValue = 1.0;
+    _lastFocalPoint = details.focalPoint;
+
+    final scope = ZTimelineScope.of(context);
+    scope.interaction.setGrabbing(true);
+  }
+
+  void _handleScaleUpdate(ScaleUpdateDetails details) {
+    final scope = ZTimelineScope.of(context);
+    final config = scope.config;
+    final width = _width;
+
+    // Two-finger pinch-to-zoom
+    if (details.pointerCount >= 2 && config.enablePinchZoom) {
+      if (details.scale != _prevScaleValue) {
+        final scaleFactor = details.scale / _prevScaleValue;
+        _prevScaleValue = details.scale;
+
+        final focalPosition = (details.focalPoint.dx / width).clamp(0.0, 1.0);
+        _performZoom(scaleFactor, focusPosition: focalPosition);
+      }
+    }
+    // Single-finger pan
+    else if (details.pointerCount == 1 &&
+        config.enablePan &&
+        !scope.interaction.isDraggingEntry) {
+      if (_lastFocalPoint != null) {
+        final diff = details.focalPoint - _lastFocalPoint!;
+        final ratio = -diff.dx / width;
+
+        if (ratio != 0) {
+          scope.viewport.pan(ratio);
+        }
+      }
+    }
+
+    _lastFocalPoint = details.focalPoint;
+  }
+
+  void _handleScaleEnd(ScaleEndDetails details) {
+    _lastFocalPoint = null;
+
+    final scope = ZTimelineScope.of(context);
+    scope.interaction.setGrabbing(false);
+  }
+
+  void _handlePointerSignal(PointerSignalEvent event) {
+    if (event is! PointerScrollEvent) return;
+
+    final scope = ZTimelineScope.of(context);
+    final config = scope.config;
+    final width = _width;
+
+    final pressed = HardwareKeyboard.instance.logicalKeysPressed;
+    final isCtrlOrMeta =
+        pressed.contains(LogicalKeyboardKey.controlLeft) ||
+        pressed.contains(LogicalKeyboardKey.controlRight) ||
+        pressed.contains(LogicalKeyboardKey.metaLeft) ||
+        pressed.contains(LogicalKeyboardKey.metaRight);
+
+    // Ctrl/Cmd + scroll = zoom
+    if (isCtrlOrMeta && config.enableMouseWheelZoom) {
+      final renderBox = context.findRenderObject() as RenderBox?;
+      final local = renderBox?.globalToLocal(event.position) ?? Offset.zero;
+      final focusPosition = (local.dx / width).clamp(0.0, 1.0);
+      final factor = event.scrollDelta.dy < 0
+          ? config.zoomFactorIn
+          : config.zoomFactorOut;
+      _performZoom(factor, focusPosition: focusPosition);
+      return;
+    }
+
+    // Horizontal scroll = pan
+    if (config.enablePan) {
+      final dx = event.scrollDelta.dx;
+      if (dx == 0.0) return;
+
+      final ratio = dx / width;
+      if (ratio != 0) {
+        scope.viewport.pan(ratio);
+      }
+    }
+  }
+
+  void _performZoom(double factor, {double focusPosition = 0.5}) {
+    final scope = ZTimelineScope.of(context);
+    final config = scope.config;
+    final viewport = scope.viewport;
+
+    // Check limits before zooming
+    final currentDuration = viewport.end.difference(viewport.start);
+    final newDurationMs = (currentDuration.inMilliseconds / factor).round();
+    final newDuration = Duration(milliseconds: newDurationMs);
+
+    // Prevent zooming in too far
+    if (factor > 1 && newDuration < config.minZoomDuration) return;
+    // Prevent zooming out too far
+    if (factor < 1 && newDuration > config.maxZoomDuration) return;
+
+    viewport.zoom(factor, focusPosition: focusPosition);
+  }
+
+  Map<ShortcutActivator, VoidCallback> _buildKeyboardBindings(
+    ZTimelineScopeData scope,
+  ) {
+    final config = scope.config;
+
+    if (!config.enableKeyboardShortcuts) {
+      return const {};
+    }
+
+    return {
+      // Pan left
+      const SingleActivator(LogicalKeyboardKey.arrowLeft): () {
+        if (config.enablePan) {
+          scope.viewport.pan(-config.keyboardPanRatio);
+        }
+      },
+      // Pan right
+      const SingleActivator(LogicalKeyboardKey.arrowRight): () {
+        if (config.enablePan) {
+          scope.viewport.pan(config.keyboardPanRatio);
+        }
+      },
+      // Zoom in (equals key, typically + without shift)
+      const SingleActivator(LogicalKeyboardKey.equal): () {
+        _performZoom(config.zoomFactorIn);
+      },
+      // Zoom out
+      const SingleActivator(LogicalKeyboardKey.minus): () {
+        _performZoom(config.zoomFactorOut);
+      },
+      // Zoom in (numpad +)
+      const SingleActivator(LogicalKeyboardKey.numpadAdd): () {
+        _performZoom(config.zoomFactorIn);
+      },
+      // Zoom out (numpad -)
+      const SingleActivator(LogicalKeyboardKey.numpadSubtract): () {
+        _performZoom(config.zoomFactorOut);
+      },
+    };
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final scope = ZTimelineScope.of(context);
+
+    return CallbackShortcuts(
+      bindings: _buildKeyboardBindings(scope),
+      child: Focus(
+        autofocus: widget.autofocus,
+        focusNode: _focusNode,
+        child: Listener(
+          onPointerSignal: _handlePointerSignal,
+          child: ListenableBuilder(
+            listenable: scope.interaction,
+            builder: (context, child) {
+              return MouseRegion(
+                cursor: scope.interaction.isGrabbing
+                    ? SystemMouseCursors.grabbing
+                    : SystemMouseCursors.grab,
+                child: child,
+              );
+            },
+            child: GestureDetector(
+              onScaleStart: _handleScaleStart,
+              onScaleUpdate: _handleScaleUpdate,
+              onScaleEnd: _handleScaleEnd,
+              behavior: HitTestBehavior.deferToChild,
+              child: widget.child,
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}

packages/z-timeline/lib/src/widgets/timeline_scope.dart

@@ -0,0 +1,130 @@
+import 'package:flutter/material.dart';
+
+import '../models/interaction_config.dart';
+import '../state/timeline_interaction_notifier.dart';
+import '../state/timeline_viewport_notifier.dart';
+
+/// Provides timeline viewport and interaction state to descendants.
+///
+/// Similar to Flutter's Theme or MediaQuery pattern. Wrap your timeline
+/// widgets with this scope to enable interactions.
+///
+/// ```dart
+/// ZTimelineScope(
+///   viewport: myViewportNotifier,
+///   config: const ZTimelineInteractionConfig(
+///     minZoomDuration: Duration(days: 1),
+///   ),
+///   child: ZTimelineInteractor(
+///     child: ZTimelineView(...),
+///   ),
+/// )
+/// ```
+class ZTimelineScope extends StatefulWidget {
+  const ZTimelineScope({
+    required this.viewport,
+    required this.child,
+    this.config = ZTimelineInteractionConfig.defaults,
+    super.key,
+  });
+
+  /// The viewport notifier managing the visible time domain.
+  final TimelineViewportNotifier viewport;
+
+  /// Configuration for interaction behavior.
+  final ZTimelineInteractionConfig config;
+
+  /// The widget subtree that can access this scope.
+  final Widget child;
+
+  /// Get the nearest [ZTimelineScopeData] or throw an assertion error.
+  static ZTimelineScopeData of(BuildContext context) {
+    final data = maybeOf(context);
+    assert(
+      data != null,
+      'No ZTimelineScope found in context. '
+      'Wrap your widget tree with ZTimelineScope.',
+    );
+    return data!;
+  }
+
+  /// Get the nearest [ZTimelineScopeData] or null if not found.
+  static ZTimelineScopeData? maybeOf(BuildContext context) {
+    return context
+        .dependOnInheritedWidgetOfExactType<_ZTimelineScopeInherited>()
+        ?.data;
+  }
+
+  @override
+  State<ZTimelineScope> createState() => _ZTimelineScopeState();
+}
+
+class _ZTimelineScopeState extends State<ZTimelineScope> {
+  late final ZTimelineInteractionNotifier _interactionNotifier;
+
+  @override
+  void initState() {
+    super.initState();
+    _interactionNotifier = ZTimelineInteractionNotifier();
+  }
+
+  @override
+  void dispose() {
+    _interactionNotifier.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return _ZTimelineScopeInherited(
+      data: ZTimelineScopeData(
+        viewport: widget.viewport,
+        interaction: _interactionNotifier,
+        config: widget.config,
+      ),
+      child: widget.child,
+    );
+  }
+}
+
+class _ZTimelineScopeInherited extends InheritedWidget {
+  const _ZTimelineScopeInherited({required this.data, required super.child});
+
+  final ZTimelineScopeData data;
+
+  @override
+  bool updateShouldNotify(_ZTimelineScopeInherited oldWidget) {
+    return data != oldWidget.data;
+  }
+}
+
+/// Data provided by [ZTimelineScope].
+@immutable
+class ZTimelineScopeData {
+  const ZTimelineScopeData({
+    required this.viewport,
+    required this.interaction,
+    required this.config,
+  });
+
+  /// The viewport notifier for domain state (start/end times).
+  final TimelineViewportNotifier viewport;
+
+  /// The interaction notifier for transient UI state (grabbing, dragging).
+  final ZTimelineInteractionNotifier interaction;
+
+  /// Configuration for interaction behavior.
+  final ZTimelineInteractionConfig config;
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other)) return true;
+    return other is ZTimelineScopeData &&
+        other.viewport == viewport &&
+        other.interaction == interaction &&
+        other.config == config;
+  }
+
+  @override
+  int get hashCode => Object.hash(viewport, interaction, config);
+}

packages/z-timeline/lib/src/widgets/timeline_view.dart

@@ -0,0 +1,291 @@
+import 'package:flutter/material.dart';
+
+import '../constants.dart';
+import '../models/entry_drag_state.dart';
+import '../models/projected_entry.dart';
+import '../models/timeline_entry.dart';
+import '../models/timeline_group.dart';
+import '../services/timeline_projection_service.dart';
+import '../state/timeline_viewport_notifier.dart';
+import 'draggable_event_pill.dart';
+import 'ghost_overlay.dart';
+import 'group_drop_target.dart';
+import 'timeline_scope.dart';
+
+typedef EntryLabelBuilder = String Function(TimelineEntry entry);
+typedef EntryColorBuilder = Color Function(TimelineEntry entry);
+
+/// Callback signature for when an entry is moved via drag-and-drop.
+typedef OnEntryMoved =
+    void Function(
+      TimelineEntry entry,
+      DateTime newStart,
+      String newGroupId,
+      int newLane,
+    );
+
+/// Base timeline view: renders groups with between-group headers and
+/// lane rows containing event pills.
+class ZTimelineView extends StatelessWidget {
+  const ZTimelineView({
+    super.key,
+    required this.groups,
+    required this.entries,
+    required this.viewport,
+    required this.labelBuilder,
+    required this.colorBuilder,
+    this.laneHeight = ZTimelineConstants.laneHeight,
+    this.groupHeaderHeight = ZTimelineConstants.groupHeaderHeight,
+    this.onEntryMoved,
+    this.enableDrag = true,
+  });
+
+  final List<TimelineGroup> groups;
+  final List<TimelineEntry> entries;
+  final TimelineViewportNotifier viewport;
+  final EntryLabelBuilder labelBuilder;
+  final EntryColorBuilder colorBuilder;
+  final double laneHeight;
+  final double groupHeaderHeight;
+
+  /// Callback invoked when an entry is moved via drag-and-drop.
+  ///
+  /// The consumer is responsible for updating their state with the new
+  /// position. The [newLane] is calculated to avoid collisions.
+  final OnEntryMoved? onEntryMoved;
+
+  /// Whether drag-and-drop is enabled.
+  final bool enableDrag;
+
+  @override
+  Widget build(BuildContext context) {
+    return AnimatedBuilder(
+      animation: viewport,
+      builder: (context, _) {
+        final projected = const TimelineProjectionService().project(
+          entries: entries,
+          domainStart: viewport.start,
+          domainEnd: viewport.end,
+        );
+
+        return LayoutBuilder(
+          builder: (context, constraints) {
+            final contentWidth = constraints.maxWidth.isFinite
+                ? constraints.maxWidth
+                : ZTimelineConstants.minContentWidth;
+
+            return ListView.builder(
+              itemCount: groups.length,
+              itemBuilder: (context, index) {
+                final group = groups[index];
+                final groupEntries =
+                    projected[group.id] ?? const <ProjectedEntry>[];
+                final lanesCount = _countLanes(groupEntries);
+
+                return Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    _GroupHeader(title: group.title, height: groupHeaderHeight),
+                    _GroupLanes(
+                      group: group,
+                      entries: groupEntries,
+                      allEntries: entries,
+                      viewport: viewport,
+                      lanesCount: lanesCount,
+                      laneHeight: laneHeight,
+                      colorBuilder: colorBuilder,
+                      labelBuilder: labelBuilder,
+                      contentWidth: contentWidth,
+                      onEntryMoved: onEntryMoved,
+                      enableDrag: enableDrag,
+                    ),
+                  ],
+                );
+              },
+            );
+          },
+        );
+      },
+    );
+  }
+
+  int _countLanes(List<ProjectedEntry> entries) {
+    var maxLane = 0;
+    for (final e in entries) {
+      if (e.entry.lane > maxLane) maxLane = e.entry.lane;
+    }
+    return maxLane.clamp(0, 1000); // basic guard
+  }
+}
+
+class _GroupHeader extends StatelessWidget {
+  const _GroupHeader({required this.title, required this.height});
+  final String title;
+  final double height;
+
+  @override
+  Widget build(BuildContext context) {
+    final scheme = Theme.of(context).colorScheme;
+    return Container(
+      height: height,
+      alignment: Alignment.centerLeft,
+      decoration: BoxDecoration(
+        color: scheme.surfaceContainerHighest,
+        border: Border(
+          bottom: BorderSide(
+            color: Theme.of(context).colorScheme.outlineVariant,
+          ),
+          top: BorderSide(color: Theme.of(context).colorScheme.outlineVariant),
+        ),
+      ),
+      child: Text(title, style: Theme.of(context).textTheme.titleSmall),
+    );
+  }
+}
+
+class _GroupLanes extends StatelessWidget {
+  const _GroupLanes({
+    required this.group,
+    required this.entries,
+    required this.allEntries,
+    required this.viewport,
+    required this.lanesCount,
+    required this.laneHeight,
+    required this.labelBuilder,
+    required this.colorBuilder,
+    required this.contentWidth,
+    required this.onEntryMoved,
+    required this.enableDrag,
+  });
+
+  final TimelineGroup group;
+  final List<ProjectedEntry> entries;
+  final List<TimelineEntry> allEntries;
+  final TimelineViewportNotifier viewport;
+  final int lanesCount;
+  final double laneHeight;
+  final EntryLabelBuilder labelBuilder;
+  final EntryColorBuilder colorBuilder;
+  final double contentWidth;
+  final OnEntryMoved? onEntryMoved;
+  final bool enableDrag;
+
+  @override
+  Widget build(BuildContext context) {
+    final scope = ZTimelineScope.maybeOf(context);
+
+    // If no scope (drag not enabled), use static height
+    if (scope == null || !enableDrag) {
+      return _buildContent(context, lanesCount);
+    }
+
+    // Listen to interaction notifier for drag state changes
+    return ListenableBuilder(
+      listenable: scope.interaction,
+      builder: (context, _) {
+        final effectiveLanesCount = _calculateEffectiveLanesCount(
+          actualLanesCount: lanesCount,
+          dragState: scope.interaction.dragState,
+          groupId: group.id,
+        );
+
+        return _buildContent(context, effectiveLanesCount);
+      },
+    );
+  }
+
+  int _calculateEffectiveLanesCount({
+    required int actualLanesCount,
+    required EntryDragState? dragState,
+    required String groupId,
+  }) {
+    // No drag active - use actual lane count
+    if (dragState == null) {
+      return actualLanesCount;
+    }
+
+    // Drag active but over different group - use actual lane count
+    if (dragState.targetGroupId != groupId) {
+      return actualLanesCount;
+    }
+
+    // Drag active over this group - expand to accommodate target lane
+    return actualLanesCount > dragState.targetLane
+        ? actualLanesCount
+        : dragState.targetLane;
+  }
+
+  Widget _buildContent(BuildContext context, int effectiveLanesCount) {
+    final totalHeight =
+        effectiveLanesCount * laneHeight +
+        (effectiveLanesCount > 0
+            ? (effectiveLanesCount - 1) * ZTimelineConstants.laneVerticalSpacing
+            : 0);
+    final scope = ZTimelineScope.maybeOf(context);
+
+    // The inner Stack with pills and ghost overlay
+    Widget innerStack = SizedBox(
+      height: totalHeight,
+      width: double.infinity,
+      child: Stack(
+        children: [
+          // Event pills
+          for (final e in entries)
+            DraggableEventPill(
+              entry: e,
+              laneHeight: laneHeight,
+              labelBuilder: labelBuilder,
+              colorBuilder: colorBuilder,
+              contentWidth: contentWidth,
+              enableDrag: enableDrag,
+            ),
+
+          // Ghost overlay (rendered in same coordinate space as pills)
+          if (enableDrag && scope != null)
+            ListenableBuilder(
+              listenable: scope.interaction,
+              builder: (context, _) {
+                final dragState = scope.interaction.dragState;
+                if (dragState == null || dragState.targetGroupId != group.id) {
+                  return const SizedBox.shrink();
+                }
+                return GhostOverlay(
+                  dragState: dragState,
+                  viewport: viewport,
+                  contentWidth: contentWidth,
+                  laneHeight: laneHeight,
+                );
+              },
+            ),
+        ],
+      ),
+    );
+
+    // Wrap with DragTarget if drag is enabled
+    if (enableDrag && onEntryMoved != null) {
+      innerStack = GroupDropTarget(
+        group: group,
+        entries: entries,
+        allEntries: allEntries,
+        viewport: viewport,
+        contentWidth: contentWidth,
+        laneHeight: laneHeight,
+        lanesCount: lanesCount,
+        onEntryMoved: onEntryMoved,
+        child: innerStack,
+      );
+    }
+
+    return AnimatedSize(
+      duration: const Duration(milliseconds: 150),
+      curve: Curves.easeInOut,
+      alignment: Alignment.topCenter,
+      child: Padding(
+        padding: EdgeInsets.symmetric(
+          vertical: ZTimelineConstants.verticalOuterPadding,
+        ),
+        child: innerStack,
+      ),
+    );
+  }
+}