df12 Productions — Library API: time-travel state

Frankie also exposes a stable library-facing time-travel state API under frankie::time_travel. Embedding hosts and alternative front ends can import TimeTravelInitParams and TimeTravelState directly, construct state without depending on crate::tui, and read the documented getter surface.

use chrono::Utc;
use frankie::local::{CommitMetadata, CommitSha, CommitSnapshot, RepoFilePath};
use frankie::time_travel::{TimeTravelInitParams, TimeTravelState};

let metadata = CommitMetadata::new(
    "abc1234567890".to_owned(),
    "Fix login validation".to_owned(),
    "Alice".to_owned(),
    Utc::now(),
);
let snapshot = CommitSnapshot::with_file_content(
    metadata,
    "src/auth.rs".to_owned(),
    "fn login() {}".to_owned(),
);

let state = TimeTravelState::new(TimeTravelInitParams {
    snapshot,
    file_path: RepoFilePath::new("src/auth.rs".to_owned()),
    original_line: Some(42),
    line_mapping: None,
    commit_history: vec![CommitSha::new("abc1234567890".to_owned())],
    current_index: 0,
});

assert_eq!(state.file_path().as_str(), "src/auth.rs");
assert_eq!(state.original_line(), Some(42));
assert_eq!(state.commit_count(), 1);
assert_eq!(state.snapshot().message(), "Fix login validation");

`load_time_travel_state`

pub fn load_time_travel_state(
    git_ops: &dyn GitOperations,
    params: &TimeTravelParams,
    head_sha: Option<&CommitSha>,
    commit_history_limit: usize,
) -> Result<TimeTravelState, GitOperationError>

load_time_travel_state is the primary library entry point for constructing a TimeTravelState from live Git data. Use it when an embedding host wants Frankie to read the commit snapshot, enumerate parent commits, and prepare the navigation state from a real repository; construct TimeTravelState directly with TimeTravelInitParams only when you already have all of that data in memory.

Table: Parameters for load_time_travel_state.

Parameter	Description
`git_ops`	Implementation of `GitOperations` that provides commit, snapshot, and parent-history access.
`params`	`TimeTravelParams` carrying the review comment's file path and commit SHA.
`head_sha`	Optional `HEAD` SHA used to verify whether the stored line mapping is still current.
`commit_history_limit`	Maximum number of parent commits to load; values below `1` are clamped to `1`.

The function returns GitOperationError when the referenced commit cannot be found in the local repository, the commit snapshot cannot be read, or parent commit enumeration fails.

use frankie::local::{CommitSha, GitOperationError, GitOperations};
use frankie::time_travel::{TimeTravelParams, load_time_travel_state};

# struct StubGitOps;
# impl GitOperations for StubGitOps {
#     fn get_commit_snapshot<'a>(
#         &self,
#         _sha: &'a CommitSha,
#         _file_path: Option<&'a frankie::local::RepoFilePath>,
#     ) -> Result<frankie::local::CommitSnapshot, GitOperationError> {
#         unimplemented!()
#     }

#     fn get_file_at_commit(
#         &self,
#         _sha: &CommitSha,
#         _file_path: &frankie::local::RepoFilePath,
#     ) -> Result<String, GitOperationError> {
#         unimplemented!()
#     }

#     fn verify_line_mapping(
#         &self,
#         _request: &frankie::local::LineMappingRequest,
#     ) -> Result<frankie::local::LineMappingVerification, GitOperationError> {
#         unimplemented!()
#     }

#     fn get_parent_commits(
#         &self,
#         _sha: &CommitSha,
#         _limit: usize,
#     ) -> Result<Vec<CommitSha>, GitOperationError> {
#         unimplemented!()
#     }

#     fn commit_exists<'a>(&self, _sha: &'a CommitSha) -> bool {
#         true
#     }
#
# }

# fn example(git_ops: &dyn GitOperations) -> Result<(), GitOperationError> {
let params = TimeTravelParams::new(
    CommitSha::new("abc1234567890".to_owned()),
    "src/auth.rs".into(),
    Some(42),
);
let state = load_time_travel_state(git_ops, &params, None, 50)?;

assert_eq!(state.commit_count(), 1);
# Ok(())
# }

`navigate_time_travel_state`

pub fn navigate_time_travel_state(
    git_ops: &dyn GitOperations,
    state: &TimeTravelState,
    direction: TimeTravelNavigationDirection,
    head_sha: Option<&CommitSha>,
) -> Result<Option<TimeTravelState>, GitOperationError>

Use navigate_time_travel_state when a TimeTravelState is already loaded and Frankie should move to the next newer or previous older commit without depending on the TUI adapter. The function preserves the loaded TimeTravelState, recalculates the target index in shared library code, and returns Ok(None) when navigation is unavailable at the current history boundary.

Table: Parameters for navigate_time_travel_state.

Parameter	Description
`git_ops`	Implementation of `GitOperations` used to load the target commit snapshot.
`state`	Existing public `TimeTravelState` to navigate from.
`direction`	`TimeTravelNavigationDirection::Next` or `::Previous`.
`head_sha`	Optional `HEAD` SHA used to refresh line mapping for the target snapshot.

No new standalone CLI mode is added for this library-first extraction. The interactive TUI keeps the existing t, h, l, and Esc workflow while delegating the underlying load-and-navigate orchestration to the shared API.