filmopen_browser

A snapshot

This specification is a copy of docs/software/packages/filmopen_browser.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.

The pages: the browser page with the tree pane and the detail pane, the entity page (header, version row, tabs: the form, Script, Workflow, Compare, Takes, Commentary), the epoch overview (a character’s cards listing its outfits at each epoch, with New outfit, which asks a name only), the category lists (Add character, Add location and Add prop), the Script page, in three tabs — Contents, Script and Workflow —, the Workflow tab (the chosen scriptwriting plug-in’s steps, each with whether it is done and the model it will use, under the Create Script card on the Script page, on every folder’s and scene’s page too; Run asks the step’s fields in a dialog with what the run will cost about and where it stops, runs it on the entity the row stands under — the run held while the app is open (workflowRunsProvider) —, and shows its progress, Stop, its spend, its text or failure, and Show the script; below the steps, the media sections — the focus’s characters with their outfits, locations, props and scenes, then the project’s other characters and locations, those in no scene marked Not in any scene, each version’s media card once, with a checkbox on each place the viewer may write and Select all / Select none per section, workflow_media.dart, which keeps each offered place’s target; and Render {n}, fixed at the tab’s bottom right, which settles the drafts, decides each ticked prompt’s writer, asks each such place whether its render can run and leaves out those no words could help, shows a prompts summary first where a model would write one of the rest, writes them, prepares each checked place still offered but those left out, shows a summary of what is ready, what is skipped and why and what Basic wrote free, and on its word adds the ready ones to the batch and submits exactly them, workflow_render.dart), the Contents card (a folder’s contents, or the script’s, as a file manager shows them, with Add folder… and Add scene… over the rows and a menu on each, which a folder’s page shows above its form), the Script tab (script_tab.dart: a scene, a folder or the whole film read as a screenplay page, as a grid of scene cards or as a timeline of the scenes by page length with a lane per character (filmopen_ui’s ScriptTimeline), each run of scenes headed by its folders, a card opening its scene; a folder’s and the whole film’s narrowed by script_filters.dart’s chips, pull-downs and search, kept per film in scriptViewProvider, a scene opened by itself always whole), the project overview and chooser, the render batch record and the one set page that shows a comp, an assistant session or a render queue (sets/set_list_page.dart), a discarded version’s notice, with no action, the other files. The Takes tab draws each take with filmopen_media_ui’s MediaTile, wearing its own batch’s provenance strip, above its caption. The comps are its part too: Add to comp on a placed medium’s menu (sets/comp_action.dart, held by the browser page while it is mounted) and the comp’s page (sets/comp_page.dart) — the pending comp’s title, description and visibility autosaved with POST beside them, a posted comp read with Open in browser and Share. The render queue is its part as well: a render batch waiting to be sent opens on the queue’s page (sets/queue_page.dart) — its rows with their states, Render on the viewer’s own pending batch, the interrupted pass and the unresolved items, each item’s job followed to its take and record, and Add again on a refused row.

Flutter. 30 files, 9,580 lines under lib/; 165 tests in 16 files. Barrel: lib/filmopen_browser.dart.

Depends on

• filmopen_format — uses Author, Catalogue, ChildProblem, CommentaryEntry, Entity, EntityGroup, EntityType, EntityVersions, EpochDeclaration, ExactDecimal, FileMedia, FileNameParser, FilmProject, MediaEntry, MediaSlot, Money, PickReason, PromptPath, PromptState, ReferenceCodec, ReferenceKind, ReferenceTarget, ReferenceToken, Resolution, SceneCard, ScriptBlock, ScriptOutline, ScriptRow, SetRecord, ShortName and 28 more
• filmopen_store — uses AppLog, Guards, canCreateProjects, rfc3339Now
• filmopen_state — uses BatchSelection, BrowserController, CategorySelection, CompPostException, CompPostOutcome, DecidedModel, DraftRefusal, DraftWriteContext, EntitySelection, GuardNotice, ImportProposal, ImportProposals, MediaEntryAction, MediaEntryActionAvailability, MediaEntryActionAvailable, MediaEntryActionContext, MediaEntryActionReason, MediaEntryActionUnavailable, MediaEntryActions, NavIndex, OpenDraft, OpenDrafts, OtherFilesSelection, PageAccess, PendingSelection, PendingSets, PluginCallControl, PluginCallDone, PluginCallFailed, PluginCatalogueView and 53 more
• filmopen_assistant_ui — uses nothing by name the digest could see
• filmopen_media — uses MediaProvenance, MediaStore, ProjectMedia, epochPictureFor
• filmopen_media_ui — uses Function, MediaTile, factLines, mediaStateOf, provenanceLines, provenanceText, showMediaViewer
• filmopen_ui — uses AppColors, Breakpoints, ChromeClearance, DisclosureCard, EmptyState, InfoChip, SceneGrid, SceneGridEntry, ScreenplayScene, ScreenplayView, ScriptTimeline, SectionCard, SidebarSplitView, TimelineColouring, TimelineLane, TimelineLayout, TimelineRule, TimelineScene, iconFor, imageProviderFor, kLongMessage, kMonoFontFallback, resolveMentions, showMessage, showMessageOn
• filmopen_l10n — uses fieldLabel
• filmopen_dictation — uses DictateButton, DictationTarget
• filmopen_tree — uses RowMenuButton, ScriptActions, TreePane, addableTypes, copySessionToFolder, showNewEntityDialog
• filmopen_forms — uses BlockMediaPlaces, DraftSaver, EntityCreation, EntityCreationScope, EntityDataTab, EntityFileMenu, EntityForm, GuardLine, MediaFormCard, WriteActions, WriteRefusal, guardNoticeText, promptWriterTokens, showImportReview, workflowBlockGroups, workflowMediaGroups
• filmopen_prompt_ui — uses askWriter, generateKey, generateReads, promptByWriter, promptFieldFocused, promptHolderUpdated, promptWriterTarget, promptWritten, startingPromptWriter, withWords, writerAnswerLine
• filmopen_insertion — uses BlockPlace, Function, InsertionTarget, SlotPlace, producerFailureOf
• filmopen_insertion_ui — uses Function, PlaceSelection
• filmopen_compare — uses CompareTab, SessionPage, showCompareForkDialog
• filmopen_timeline_ui — uses TimelineDockFrame
• filmopen_test_support (dev) — uses nothing by name the digest could see
• filmopen_exchange (dev) — uses nothing by name the digest could see

Third-party: flutter_riverpod, url_launcher.

Used by

filmopen_app

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/batch_detail.dart

• class BatchDetail — One render batch: how a set of takes was produced (§12.2); or a pending set’s record, or the viewer’s pending set of a type, each on the one [SetListPage] (§12.7).
  • const BatchDetail({super.key, required this.project, required String this.stem}) — The record [stem] names: a render batch, else a set’s record.
  • const BatchDetail.pending({super.key, required this.project, required EntityType this.pending}) — The viewer’s pending set of [pending], or the page saying what fills it.
  • final FilmProject project
  • final String? stem — The record’s stem — a render batch’s or a set’s — or null for [pending].
  • final EntityType? pending — The type whose pending set the page shows — a comp, an assistant session or a render queue — or null for [stem].

lib/src/browser_page.dart

• class BrowserPage — The project browser: the tree beside the selected object, or — below Breakpoints.treeInDrawer of window width — the object alone, the tree in the dashboard’s drawer beside the rail, as [BrowserTree] (§9.1).
  • const BrowserPage({super.key})
• class BrowserTree — The project’s tree as a region of its own: beside the page on a wide window, in the dashboard’s drawer below Breakpoints.treeInDrawer (§9.1).
  • const BrowserTree({super.key, this.onNavigated}) — The tree; [onNavigated] is called when a tap has navigated somewhere.
  • final VoidCallback? onNavigated — Called when a tap on a row has navigated: the drawer closes on it.

lib/src/category_view.dart

• class CategoryView — Every entity of one type as a list.
  • const CategoryView({super.key, required this.project, required this.type})
  • final FilmProject project
  • final EntityType type

lib/src/check_popover.dart

• typedef typedef AssistantWrite — The version an assistant’s change wrote, for the box at its check (§9.3): its stem, and which write it was.
• variable final assistantWriteProvider — The last version an assistant’s change wrote while the page shows it; null once the page moves elsewhere.
• class AssistantWriteNotifier — Holds the last [AssistantWrite], set at each verified write and cleared by any move to another page (§9.3).
  • void written(String stem) — A verified write of [stem]: the box shows again, even over the same version.
• function bool openAssistantWrite(WidgetRef ref, String stem) — Opens the version an assistant’s update-entity or create-entity wrote, with the box at its check (§9.3).
• class CheckPopover — A box that tapers at its top into an arrow pointing at [child], the version row’s check (§9.3).
  • const CheckPopover({ super.key, required this.child, required this.kind, required this.message, this.showing, this.actionLabel, this.onAction, this… — A box of [message] at [child], shown while [showing] is set, logged as [kind].
  • final Widget child — The check the arrow points at.
  • final Object? showing — What the box is shown for, such as one write; null hides it.
  • final String kind — write or use, for the log.
  • final String message — The box’s sentence, wrapped to its width.
  • final String? actionLabel — The label of a link in the box, which dismisses it and then calls [onAction]; none where null.
  • final VoidCallback? onAction — What the link does once the box is gone.
  • final String? secondaryLabel — The label of a second link, before [actionLabel], whose identifier is <identifier>.secondary; none where null.
  • final VoidCallback? onSecondary — What the second link does once the box is gone.
  • final bool danger — Whether the box asks for a decision the page waits on, such as the assistant’s draft: bordered in the theme’s error colour, and kept through a tap outside it and a scroll (§9.3).
  • final String? identifier — The box’s semantics identifier; its link’s is <identifier>.action.
  • final bool compact — The smaller box of a short sentence, such as Use this version (§9.3): [compactWidth] wide.
  • final Map<String, Object?> trail — The facts the shown event carries beside the kind: the version’s stem, the reason it is shown.
  • static const maxWidth — The widest the box is drawn.
  • static const compactWidth — The width of a [compact] box.
  • static const margin — The least room the box keeps from the view’s edges.
  • static void dismissFrom(BuildContext context) — Dismisses the box around [context] as check, the check’s own activation: a click, a key or a screen reader’s tap.

lib/src/commentary_tab.dart

• class CommentaryTab — Every author’s commentary on this entity, consolidated into one feed (§13.4).
  • const CommentaryTab({super.key, required this.project, required this.group})
  • final FilmProject project
  • final EntityGroup group

lib/src/detail_pane.dart

• class DetailPane — The main area: whatever the current [Selection] names.
  • const DetailPane({super.key})

lib/src/entity_detail.dart — without reportSettledTab

• class EntityDetail — One entity: header, epoch choice and version row, then tabs over the chosen version file.
  • const EntityDetail({super.key, required this.project, required this.selection})
  • final FilmProject project
  • final EntitySelection selection
• enum EntityTabId — Which tab a page is showing, so a selection survives a change of the tab set (a scene and a folder have a Script tab and a Workflow tab, and no other type does).
  • values: data, script, workflow, compare, takes, commentary
• class StalePickBanner — §13.2: the project chose another version after this author picked theirs.
  • const StalePickBanner({super.key, required this.onAbandon, required this.onKeep})
  • final VoidCallback onAbandon
  • final VoidCallback onKeep

lib/src/entity_tabs.dart

• class EntityTabs — The tabs of one entity page, with a controller of its own rather than a [DefaultTabController], because two of them can refuse to open (§9.3).
  • const EntityTabs({ super.key, required this.ids, required this.labels, required this.views, required this.blockedReason, required this.above, this.…
  • final String? shownStem — The full stem of the version the tabs are over: another, in the same tabs, is another place (§6.11a).
  • final void Function(Object owner, T? id)? onSettled — Told the tab shown, with these tabs’ state as the owner, after the frame and once per version and tab; null once the tabs are gone.
  • final T? requested — A tab the page was asked to open — Compare after a write the app made (§13.3) — opened once for each [request], where it can be opened.
  • final Object? request — What asked for [requested]: another opens it again, the same one never does, so that a rebuild leaves the reader on whichever tab they chose since.
  • final List<T> ids — What each tab is, so a selection survives a change of the tab set.
  • final List<String> labels
  • final List<Widget> views
  • final List<String?> blockedReason — Null where the tab opens; otherwise the sentence saying why it does not.
  • final Set<T> intercepted — Tappable, but the tap runs [onIntercept] instead of opening.
  • final Future<T?> Function(T id)? onIntercept — Answers with the tab to open, or null to stay where the page was.
  • final Widget above — The header above the tab bar: it scrolls with nothing and belongs to the page, not to a tab.
  • static bool show<T>(BuildContext context, T id) — Opens the tab [id] of the nearest tabs of [T] above [context], as a tap would, where it is openable; false where there are no such tabs, [id] is not among them, or it is blocked or intercepted.

lib/src/epoch_overview.dart

• class EpochOverview — A library entity seen whole (§8.2).
  • const EpochOverview({super.key, required this.project, required this.group})
  • final FilmProject project
  • final EntityGroup group

lib/src/other_files_view.dart

• class OtherFilesView — Files the project layout or filename grammar does not describe.
  • const OtherFilesView({super.key, required this.project})
  • final FilmProject project

lib/src/outfit_list.dart

• class OutfitList — The outfits of a character at one epoch, at the foot of that epoch’s card on the character’s overview (§8.2).
  • const OutfitList({ super.key, required this.project, required this.character, required this.epoch, required this.epochName, required this.viewer, r… — The list of [character]’s outfits at [epoch], in [project], as [viewer] sees them.
  • final FilmProject project — The film the overview shows, whose outfits are listed and in which New outfit makes one.
  • final EntityGroup character — The character whose outfits these are; its tag is their tags’ prefix.
  • final String epoch — The epoch whose outfits are listed, and at which New outfit makes one.
  • final String epochName — How the card names the epoch, for the dialog’s title.
  • final Author? viewer — The username in effect, for each outfit’s version in use.
  • final String? unavailable — Why New outfit is disabled — no handle, a read-only project, an epoch the project does not declare, a character whose every version is discarded — or null; the overview decides each.

lib/src/project_chooser.dart

• class ProjectChooser — Shown when the folder holds project files from several authors (or several tags) and no official pointer.
  • const ProjectChooser({super.key, required this.project})
  • final FilmProject project

lib/src/project_overview.dart

• class ProjectOverview — The diagnostics landing when the folder has no project version (§9.3).
  • const ProjectOverview({super.key, required this.project}) — Shows the folder’s complete warnings without a duplicate project summary.
  • final FilmProject project — The folder whose diagnostics remain available without a project file.
• class ProjectWarnings — The complete folder diagnostics, folded above the project’s form (§9.3).
  • const ProjectWarnings({super.key, required this.project, this.folded = true}) — Starts folded on a version page, or open on the missing-project landing.
  • final FilmProject project — The loaded folder, including diagnostics beyond the displayed file.
  • final bool folded — Whether the card has a fold; false keeps the missing-project faults visible.

lib/src/script_tab.dart

• function ({List<ScriptRow> rows, String source, String list}) folderTabRows(ScriptOutline? outline, FilmProject project, Entity folder, {Author? viewer}) — The rows a folder’s Script and Workflow tabs read: the working list where the script draws [folder] (§5.12).
• class ScriptTab — The script of a scene, a folder or the whole film, as a screenplay page or as a grid of scene cards (§9.3).
  • const ScriptTab({ super.key, required this.project, required this.entity, this.viewer, this.editable = true, })
  • const ScriptTab.whole({super.key, required this.project, required List<ScriptRow> this.rows, this.viewer}) — The whole film’s script, from the top-level Script node: [rows] is the project file’s own list.
  • final FilmProject project — The project read, whose re-read is a new one and so a new open.
  • final Entity? entity — The scene or folder whose script this is; null for the whole film.
  • final Author? viewer — Whose world the scene’s own references are read in (§6.1 step 2) — unless the scene is the official one, which reads through official however the reader is signed in.
  • final bool editable — Whether the viewer may write this version, which its empty page’s words follow.
  • final List<ScriptRow>? rows — The rows to walk for the whole film; null for a scene or a folder, which the tab reads for itself (§5.12).
• function String folderTitle(AppLocalizations l10n, Entity folder) — A folder as a section names it: its kind and its name, Act 3: John comes home.

lib/src/sets/comp_action.dart

• variable final Set<String> compExtensions — The originals a comp takes: every media extension but GIF, BMP, MOV and FLAC, which the comps protocol’s originals do not (§9).
• function void Function() registerCompActions(ConsumerState host) — Registers Add to comp for as long as [host] is mounted, reading the film and the viewer through its ref and saying what happened through its messenger; answers the remover, for the host’s dispose.
• class CompEntryAction — Add to comp: one medium appended to the viewer’s pending comp, created where none is pending (§9).

lib/src/sets/comp_page.dart

• variable const int compTitleMax — A title’s and a description’s bounds: the comps service’s (CompsDraft).
• variable final compPostingProvider — The stems of the comps this app is posting now, kept for the app’s run (§9): a record posting whose stem is here is this app’s post, one whose stem is not was interrupted.
• class CompPostingNotifier — Holds [compPostingProvider]’s stems: one post at a time, as the poster sends one at a time (§6.17).
  • bool begin(String stem) — Marks [stem] as posting; false, with nothing changed, where a post already runs.
  • void end(String stem) — Ends [stem]’s post.
• function Future<bool> Function(Uri uri) openCompUrl — Opens a posted comp’s URL in the browser; a test stands in for it.
• class CompPage — A comp on [SetListPage]: its fields above its media, editable where [mine] — the viewer’s pending comp — else read as they are.
  • const CompPage({super.key, required this.project, required this.record, required this.mine, this.onRemove}) — The page of [record] in [project], editable where [mine] and the film may be written.
  • final FilmProject project — The film the comp is of: its media, and whether it may be written.
  • final SetRecord? record — The comp shown, or null where the viewer has no pending one.
  • final bool mine — Whether [record] is the viewer’s pending comp, which the page edits.
  • final void Function(int n)? onRemove — Removes the item numbered n; given only with [mine].

lib/src/takes_tab.dart — only TakesTab

• class TakesTab — Every take anyone has rendered for this entity, discovered by filename (§12.1).
  • const TakesTab({super.key, required this.project, required this.group, required this.current})
  • final FilmProject project
  • final EntityGroup group
  • final Entity current

lib/src/version_row.dart

• class VersionRow — Who wrote the version being looked at, which of their versions it is (a pull-down), whether it is official (star), the version in use (check), its label, and Fork.
  • const VersionRow({ super.key, required this.project, required this.versions, required this.entity, required this.viewer, required this.actions, req…
  • final FilmProject project
  • final EntityVersions versions
  • final Entity entity
  • final Author? viewer
  • final WriteActions actions
  • final PageAccess access — What the page may do, development mode included (§9.5): the star and the label follow it.
  • static String versionText(AppLocalizations l10n, Entity version) — v2, or v2 · goth when the version carries a label.
• class LabelledRow — A label beside what it names, or above it where beside would leave nothing (§9.1).
  • const LabelledRow({super.key, required this.label, required this.child})
  • final Widget label
  • final Widget child

Internal

Files under lib/ the barrel does not reach; nothing outside the package may import them.

• lib/src/contents_card.dart: ContentsCard, ContentsRows, _ContentsRow, _ContentsRowState, contentsOf
• lib/src/import_waiting_bar.dart: ImportWaitingBar
• lib/src/script_filters.dart: ScriptFilters, _ScriptFiltersState, _Picker
• lib/src/script_page.dart: ScriptPageTab, ScriptPage
• lib/src/sets/queue_page.dart: QueueRowState, QueuePage, _QueuePageState
• lib/src/sets/set_list_page.dart: SetListPage, _SetListPageState
• lib/src/workflow_media.dart: WorkflowSection, WorkflowHeading, WorkflowHeadingRow, WorkflowMediaLine, WorkflowMedia
• lib/src/workflow_render.dart: _Place, _Written, _wordsAt, _Generated, _onlyWordsCanSay, _firstFramePending, _firstFramePendingWhy, WorkflowRenderButton, _WorkflowRenderButtonState, _PromptsSummary, _PromptsSummaryState, _Summary, +1
• lib/src/workflow_run_dialog.dart: showWorkflowRunDialog, _Typed, _RunDialog, _RunDialogState
• lib/src/workflow_runs.dart: WorkflowRun, WorkflowRuns, workflowRunsProvider
• lib/src/workflow_tab.dart: WorkflowTab, _Line, _WorkflowTabState, _Elapsed, _ElapsedState