filmopen_compare

A snapshot

This specification is a copy of docs/software/packages/filmopen_compare.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

Compare: the same form twice, one field per row, the viewer’s latest on the left and the selected version on the right, with copy-left on the split — < per row, << per section, <<< in the header — through the left column’s autosave; and >, >>, >>> into the right column through its own, where it is the viewer’s own version too, and drawn nowhere else. A scene’s script pairs as a block diff (scriptDiff: a moved block is a row out and a row in), and Show changes only, kept in the settings, hides every row whose two versions are equal. SessionPage is an assistant session’s review: per item its title, its media card in View and, folded behind an arrow until opened, the same form embedded (without the media, CompareForm.withoutMedia), under compare[<n>], beside the fork’s recorded base, the patch’s before or nothing, with a Pick over each column holding a file — green where its version is in use, so the person goes back and forth — and Discard, through SessionReview.

Flutter. 6 files, 2,702 lines under lib/; 0 tests in 0 files. Barrel: lib/filmopen_compare.dart.

Depends on

• filmopen_format — uses Author, BatchStem, BlockCase, ChildEntry, CopyBlock, CopyMedia, CopyPaths, DiffKind, DiffRow, Entity, EntityType, EntityVersions, FileNameParser, FilmProject, NoCopy, Pick, RowCopy, ScriptOutline, ScriptRow, SetRecord, VersionStem, applyCopy, blockById, blockCase, blockRowIds, blocksOf, canCopy, canonicalJson, copiedKeys, deepCopy and 11 more
• filmopen_store — uses AppLog, Guards, InvalidContentException, validateContent
• filmopen_state — uses AssistantSessionLedgers, BatchSelection, BrowserController, EntitySelection, PageAccess, SessionReview, WriteProblemText, assistantSessionsProvider, browserProvider, chatOrigin, groupName, projectProvider, scriptOutlineProvider, sessionReviewProvider, settingsProvider
• filmopen_ui — uses AppColors, AttributeView, Breakpoints, ChromeClearance, EmptyState, IdentifierScope, PinnedSection, SectionCard, iconFor, showMessage
• filmopen_l10n — uses fieldLabel, flatPathLabel
• filmopen_forms — uses ComparingFields, DormantFields, DraftSaver, FormFieldSpec, FormPane, FormPullDown, FormScope, FormSectionSpec, FormSections, FormSide, GuardLine, OfficialEditBanner, SaveStatus, WriteActions, entityDataSpec, pairDrawsBlockRows, referenceMediaSection, sceneBlockMedia, sectionFields

Third-party: flutter_riverpod.

Used by

filmopen_app, filmopen_browser

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/compare_copy.dart

• enum CopyDirection — Which column a copy writes (§13.3): [left] is <, into the left column from the right; [right] is >, into the right column from the left.
  • values: left, right
• class CopyLeft — Copy-left’s controls (§13.3), in one [direction]: a < in the gutter of every row that has something to copy, a << in each section card, and a <<< over the split for the whole file — or >, >> and >>> the ot…
  • const CopyLeft({ required this.project, required this.left, required this.right, required this.readOnlyReason, this.direction = CopyDirection.left, })
  • final FilmProject project
  • final FormScope left — The left column: the viewer’s own version.
  • final FormScope right — The right column: the version they selected.
  • final CopyDirection direction — Which column this copies into.
  • FormScope get into — The column a copy writes.
  • FormScope get from — The column a copy reads.
  • final String? readOnlyReason — Why nothing may be copied, or null when [into] can be written.
  • bool get warnsOfficial — Whether a copy into this column changes what everyone sees (§13.2).
  • String identifier(String kind, [String? id]) — A control’s identifier: compare.copy-<kind>[:<id>] for <, compare.copy-<kind>-right[:<id>] for >.
  • String? blockedReason(AppLocalizations l10n) — The sentence a control that cannot be pressed carries, or null when it can be.
  • Widget? row(BuildContext context, RowCopy copy, {required String label, required String identifier, String? kind}) — The < of one row; drawn disabled, saying why, where the other version’s value is empty and this one’s is not, since an empty value is never copied over one (§9.3); null where there is otherwise nothing to copy: an e…
  • Widget? section(BuildContext context, List<RowCopy> copies, {required String identifier}) — The << of one section card: everything in it the other version has that this one does not match, in one write.
  • Widget? all(BuildContext context, List<RowCopy> copies, {String? identifier}) — The <<< over the split: every copyable key the rows offer, in one write.
• class CopyChevrons — One, two or three chevrons pointing left — the owner’s <, << and <<< — or right, for a copy into the right column.
  • const CopyChevrons(this.count, {super.key, this.size = 14, this.pointsRight = false})
  • final int count
  • final double size
  • final bool pointsRight — Whether they point right: >, >>, >>>.
  • static const double advance — How far along each chevron sits, as a fraction of its box: they overlap, or three would be 42 px wide.

lib/src/compare_fork_dialog.dart

• function Future<bool> showCompareForkDialog(BuildContext context, { required WidgetRef ref, required Entity current, required WriteActions actions, }) — What Compare asks a reader who has no version of their own (§13.3): Would you like to fork one?

lib/src/compare_form.dart

• class CompareForm — Two versions of one file as one list of paired rows (§13.3): the same sections in the same order, each field beside its twin, with the gutter down the middle.
  • const CompareForm({ super.key, required this.project, required this.left, required this.right, required this.leftEditable, required this.rightEdita…
  • final FilmProject project
  • final Entity left — The viewer’s own latest version, which they may write.
  • final Entity? right — The version they selected, written only where [rightEditable]; null where nothing stands beside the left — a version a session created —, whose rows are the left’s alone, each blank on the right (§9.3).
  • final bool leftEditable
  • final bool leftPicked — Whether the left column holds the viewer’s pick; no cell is bordered for it, the pick being the version row’s (§9.3).
  • final bool rightPicked — Whether the right column holds the viewer’s pick, as [leftPicked]; never a before column.
  • final bool embedded — One of several on a page that scrolls them (§9.3): its height is its content’s — no vertical flex, no scroll view of its own, no Show changes only, which the page’s header holds.
  • final String? idNamespace — Put before every identifier the comparison produces, where a page draws several (compare[<n>]): its copy controls are <namespace>.copy-…, its columns’ fields and controls under <namespace>.left and .right.
  • final bool rightEditable — Whether the right column may be written, and so copied into (§13.3).
  • final String? readOnlyReason — Why nothing may be copied into the left, when [leftEditable] is false: the sentence every disabled < carries.
  • final Widget Function(BuildContext context, FormScope leftScope, FormScope? rightScope, Widget copyAll)? header — Drawn above the rows and outside the scroll, given both columns’ scopes so each save status can sit with the heading it belongs to, and the gutter with copy-all both ways, so it lands on the split the rows share.
  • final void Function(Entity left)? onForkLeft — Forks the left version, for the §13.2 banner over an official left column.
  • final EdgeInsets padding
  • final EdgeInsets cardPadding
  • final double gutter
  • final bool withoutMedia — Leaves the media card’s section out of both columns, its keys still counted as shown so that they do not come back under Other attributes: the chat’s page draws the media above the comparison (§9.3).
  • final Map<String, Widget> sectionFooters — A widget drawn at the foot of each section, by the section’s id.
• class ChangesOnlyBox — The Show changes only checkbox, its label pressing it too: under the tab’s headings, and in the session review’s header, once for all its comparisons (§9.3).
  • const ChangesOnlyBox({super.key, required this.value, required this.onChanged}) — The box at [value], [onChanged] with the new one.
  • final bool value — Whether Show changes only is on.
  • final ValueChanged<bool> onChanged — Called with the new value when the box or its label is pressed.
• function List<RowCopy> everyRowCopy(FormPane left, FormPane right, {List<DiffRow>? diff, CopyDirection direction = CopyDirection.left}) — Every row’s copy in [direction], in the order the rows are drawn: what <<< (or >>>) writes.

lib/src/compare_tab.dart

• class CompareTab — Two versions of one entity side by side (§13.3): the viewer’s own latest on the left, editable, and the version they selected on the right, editable only where it is the viewer’s own too.
  • const CompareTab({ super.key, required this.project, required this.versions, required this.viewer, required this.current, this.onForkLeft, this.una…
  • final Entity? requestedLeft — The viewer’s own version the page asked the left column to show — a version the app just wrote, beside what it was made from — in place of their latest.
  • final Guards guards — The session’s policy (§9.5).
  • final String? unavailableReason — In development mode the tab is never greyed (§9.5).
  • final FilmProject project
  • final EntityVersions versions
  • final Author? viewer
  • final Entity current
  • final void Function(Entity left)? onForkLeft — Forks the left column’s version (its §13.2 banner).
  • static const double gutter — The box each direction’s copy control sits in — the gutter is two of them, < and > — and the insets the headings share with the rows so <<< and >>> land on the same split.
  • static const EdgeInsets outerPadding
  • static const EdgeInsets cardPadding
  • static const EdgeInsets tightPadding
  • static const EdgeInsets tightCardPadding
  • static String rightAccess(FilmProject project, Entity right, Author? viewer, Guards guards) — Whether the right column may be written, as the code the log carries: own where it may, else no_viewer, not_yours, library or not_writable.

lib/src/session_page.dart

• class SessionPage — An assistant session’s review (§9.3): a fixed header — The assistant’s changes with Pick all, Discard all and the summary [sessionSummaryOf] draws, beside Your current picks, over Show changes only — and…
  • const SessionPage({super.key, required this.project, required this.record}) — The review of [record], an as record of [project].
  • final FilmProject project — The opened project, whose versions the items name and the comparisons show.
  • final SetRecord record — The session’s as record, whose items the page reviews.
• function String? sessionSummaryOf(FilmProject project, SetRecord record, Author? viewer, AppLocalizations l10n) — The summary under the review’s headings, drawn from [record]’s items (§9.3), null where they say nothing.