Skip to content

feat(view): expose record timeline embedding facade#10

Merged
siriusctrl merged 3 commits into
mainfrom
agent/embedding-facade
Jul 22, 2026
Merged

feat(view): expose record timeline embedding facade#10
siriusctrl merged 3 commits into
mainfrom
agent/embedding-facade

Conversation

@siriusctrl

@siriusctrl siriusctrl commented Jul 22, 2026

Copy link
Copy Markdown
Owner

Summary

  • expose a narrow fmtview::view embedding facade around backend-neutral RecordTimeline sources
  • keep JSONL selection, crossterm polling, terminal setup/cleanup, and frame commits inside the root fmtview package
  • separate non-refreshing tail-first snapshots from live follow mode while preserving lazy older loads
  • let backward structure navigation cross an unloaded older-record boundary
  • add a complete embedding example, downstream dependency compile test, API/headless regressions, and maintainer/user documentation

Why

Fiasco and other applications need to inspect committed record timelines without depending directly on fmtview-core or reimplementing terminal lifecycle. Snapshot inspection must open at the committed tail and load history lazily, while live inspection needs the existing attached/detached/paused follow behavior.

Public contract

fmtview::view::run(
    source: Box<dyn fmtview::view::RecordTimeline>,
    options: fmtview::view::ViewOptions,
) -> fmtview::view::Result<()>

The facade fixes the view to JSONL and re-exports the complete timeline source vocabulary. ViewOptions::default() is a stable snapshot; follow = true enables refresh and follow controls.

Validation

  • cargo fmt --all --check
  • cargo test --workspace --all-targets --locked
    • includes an external temp crate that depends only on fmtview
    • includes 50 record-timeline tests covering snapshot/follow, search, structure navigation, reset, raw records, torn tails, and million-record bounded work
  • cargo clippy --workspace --all-targets --locked -- -D warnings
  • RUSTDOCFLAGS='-D warnings' cargo doc --workspace --no-deps --locked
  • cargo package -p fmtview-core --list --allow-dirty
  • cargo package -p fmtview --list --allow-dirty
  • cargo publish -p fmtview-core --dry-run --locked --allow-dirty
  • real script PTY smoke of the built embedding example using r, j, r, q
    • child exit 0 and shell state restored
    • alternate screen, mouse modes, synchronized updates, cursor restore, and cleanup ordering verified
    • raw and structured views both observed
    • evidence: target/fmtview-embedding-pty/pty.log and checks.txt in the implementation worktree

Packaging note

The root fmtview publish dry-run reaches tarball verification and then resolves the already-published crates.io fmtview-core 0.6.0, which does not contain this PR's new snapshot constructor. This PR intentionally does not change versions or publish. Per docs/releasing.md, the release that includes this change must bump both packages, publish the matching fmtview-core first, wait for registry availability, and then run the root fmtview dry-run.

Add a narrow fmtview::view entry point that accepts backend-neutral record timelines while keeping crossterm lifecycle and rendering details private. Re-export the complete source vocabulary so downstream applications only need the fmtview dependency.

Split stable snapshot viewing from live follow refresh without losing bounded tail-first history. Backward structure navigation now loads older timeline batches before reporting that no previous structure exists.

Document the embedding contract and cover snapshot, follow, lazy navigation, downstream compilation, and terminal cleanup behavior.
Separate initial tail anchoring from follow state and arm bounded older preload only after backward navigation intent.

Remove the misleading public notice option, which rendered ordinary embedder text as an error.
fix(view): keep snapshots anchored at the lazy tail
@siriusctrl
siriusctrl marked this pull request as ready for review July 22, 2026 10:22
@siriusctrl
siriusctrl merged commit fae2271 into main Jul 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant