filmopen_forms

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

One form per type in two modes — Edit on the viewer’s own writable version, View, the same boxes locked, on any other (entity_form.dart, the type→form door entity_data_spec.dart, the per-type tabs — the project’s (its subtitle font and size among its general fields, each through one logged setter for a person and an agent, a token pull-down’s choice going through a field’s own setter where it has one; its treatment’s prompt a card of its own, not folded), a character’s and a location’s (each General first and the media card below it, each prompt’s card above the place it renders — the Reference prompt above Reference images, the Sheet prompt above the sheets, a character’s Voice prompt above Voice samples (compareOnly sections, handed to the card by kind; a comparison pairs their rows instead) —, and Creator notes; a scene’s open block always shows its First frames and Last frames places, each under its First-frame or Last-frame Prompt card, whatever the media, Add a place… offering the other four, a Clip place, where shown, under the block’s clip prompt card (its writer handed the block alone and no tokens), their boxes writing the block through withBlockPrompt; a box of a prompt’s words takes away its plugin; each prompt is a promptSection, a FormSectionSpec whose body draws filmopen_prompt_ui’s PromptCard in place of the section’s card, its boxes promptFields), an outfit’s (outfit_edit_tab.dart: General with the name, the description and the condition’s chips, then the media card with its Reference prompt and Sheet prompt cards, Garments as rows, Accessories and palette, Creator notes), a prop’s (prop_edit_tab.dart: General with the kind’s chips and Hero prop‘s switch, then the media card with its Reference prompt and Sheet prompt cards, Handling and sound, Creator notes) and a folder’s (folder_edit_tab.dart: Name, Kind as chips, Synopsis, Notes; what the folder holds is the pages’ card, handed in through EntityForm.leading) and a scene’s (scene_edit_tab.dart: Name, Synopsis, one Location and one Epoch as pull-downs, Characters as rows with Add character, its menu naming each character by its picture, and, where the project declares several epochs, an epoch of the character’s own, and an outfit where the character has two or more at the entry’s epoch, Notes; then the Dialog and actions card, sceneBlocksSections: on the page the scene’s script written there — ScriptEditor (script_editor.dart) on the form’s own draft, a card per block condensed to its line until it is opened and open until the focus goes to another node or a press lands elsewhere — a parked focus, the window’s lost or a box letting go, keeps it —, the block open published as the state’s script focus and the block the timeline asks for opened while it is in charge, the speaker’s pull-down, each character by its picture, the dialogue, direction, action and duration, the block’s beats under its duration — position, description, duration, their seconds’ total and two warnings that refuse nothing, reordered by menu or drag, script.beat.* and script.beats.* logs —, its subtitles under them laid out the same, the text plain, script.subtitle.* and script.subtitles.* logs with the values entered, add, insert, delete, move up and down and a drag, and Move to scene… (script_move.dart: the target written first under its own next number, a fork where it is not the viewer’s, the block then removed and the draft settled before Moved); in a comparison a row per block, labelled by its place, its line ending with its beats’ and its subtitles’ count and seconds) — the epochs editor) — the autosave (draft_saver.dart), the JSON editor, the file menu, the write actions (fork, official, pick, label) and GuardLine, the red line of development mode. The plug-ins’ side of a page too: a card per enabled plug-in on a character’s, a location’s, a folder’s, a scene’s and the project’s form (plugin_sections.dart, fields under plugins.<tag>.<key> through the one type door, autosaved and paired in Compare like their neighbours), the plug-in field widgets a card and a plug-in’s own page both draw with (plugin_field_widgets.dart: a switch, a pull-down, a box, and what an agent’s typing parses to), and Plugins… on the file menu with its dialog (plugin_hook_dialog.dart: a plug-in’s rewrite, its progress and Stop, the version it wrote opened), all through filmopen_state’s seam, of which this package holds two roles: PluginCatalogueView for what is installed and PluginInvocation for the rewrite it runs.

Flutter. 40 files, 17,684 lines under lib/; 539 tests in 48 files. Barrel: lib/filmopen_forms.dart.

Depends on

filmopen_format — uses AgeYearRefusal, Author, Beat, BlockEdit, BlockSummaryPart, Catalogue, ChildEntry, ComposedTreatment, CopyBlock, CopyMedia, CopyPaths, DuplicateKeyException, Entity, EntityGroup, EntityType, EpochDeclaration, ExactDecimal, FileNameParser, FilmProject, MediaEntry, MediaKind, MediaLocation, MediaSlot, MediaStage, NoCopy, PathValue, ProjectKind, PromptPath, ReferenceTarget, RenderBatch and 135 more
filmopen_exchange — uses ExchangeId, FieldPath, ImportAction, ImportChange, ImportNote, ImportPlan, ImportProblem, ImportResult, ImportStage, ImportState, focus
filmopen_store — uses AppLog, EntityExistsException, EpochDeclaredPickFailedException, Guards, IdentityChangedException, NoViewerException, NotYourTakeException, TakeStillNamedException, encodeProjectJson, identityKeys, validateContent
filmopen_platform — uses canRevealFiles, revealInFileManager
filmopen_state — uses AssistantAction, AssistantCatalog, AssistantDraft, AssistantFieldAt, AssistantLevel, AssistantService, AssistantSourceBinding, AssistantUnavailable, AssistantWhereController, Attribution, CanonicalTextValue, DraftObservers, DraftRefusal, DraftWriteConflictException, DraftWriteContext, DraftsNotSettledException, EditableDraft, EntitySelection, EpochBindingChangedException, FieldRegistry, FieldSetter, FrozenAssistantDraft, GuardNotice, ImportApplied, ImportApplyAnswer, ImportApplyInFlightException, ImportApplyRefused, ImportBindingChangedException, ImportProposal, ImportProposalDroppedException and 54 more
filmopen_media — uses MediaProvenance, ProjectMedia, epochPictureFor, pictureInUse, promptTokenCandidates
filmopen_insertion — uses BlockPlace, Function, InsertionTarget, SlotPlace
filmopen_jobs — uses nothing by name the digest could see
filmopen_media_ui — uses Function, MediaTile, factLines, mediaStateOf, provenanceLines, provenanceText, showMediaViewer
filmopen_insertion_ui — uses Function, MediaPlace
filmopen_ui — uses AppColors, AttributeValue, AttributeView, Breakpoints, DisclosureCard, EditableComboBox, EditableTextTarget, GenrePicker, IdentifierScope, SectionCard, StageSelector, iconFor, imageProviderFor, kLongMessage, kMonoFontFallback, scopedId, showMessage, showMessageOn
filmopen_text_ui — uses MentionCandidates, ProseController, ProseEditor, proseChip, shownMentions
filmopen_l10n — uses fieldLabel, flatPathLabel
filmopen_assistant_ui — uses nothing by name the digest could see
filmopen_dictation — uses DictateButton, DictationTarget
filmopen_picker — uses PromptBuilderField
filmopen_prompt_ui — uses ProjectMentionCandidates, PromptCard, PromptMentionCandidates, promptTitleOf, promptTokenName, withPromptWordChanged
filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: flutter_riverpod, voo_json_tree.

Used by

filmopen_app, filmopen_browser, filmopen_compare, filmopen_plugins_ui

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/block_media_places.dart`

class BlockMediaPlaces — A block’s media under its open fields (Project Specification §10.3): the two frame places always, each under its frame prompt — a prompt is written before its image —, and a place for each other group that holds entri…
- const BlockMediaPlaces({ super.key, required this.stem, required this.draft, required this.enabled, required this.onChange, required this.id, requi… — The places of block [id] in [draft].
- final String stem — The scene’s stem, which the places’ identifiers name.
- final Map<String, dynamic> draft — The scene’s draft, read again at every build.
- final bool enabled — Whether the block may be written: the form’s FormScope.enabled.
- final ScriptChange onChange — Every change, through the scene’s draft.
- final Future<void> Function(String reference)? onDeleteTake — The page’s door once a media entry is flagged deleted; none where null.
- final Entity? entity — The scene’s file, which the frame prompts are written in; null draws no prompt.
- final DraftSaver? binding — The page’s draft, which a prompt’s Generate settles and writes through; null where read-only.
- final MentionCandidates? candidates — The project-backed mention source the prompts’ tokens read.
- final int candidatesRevision — Changes exactly when [candidates]’ or a [promptCandidates]’ list changes.
- final PromptMentionCandidates Function(String kind)? promptCandidates — The form’s @ source of a frame’s or a clip’s prompt, by the writers’ kind (§9.8).
- final List<String>? groups — The groups to draw, in the table’s order; null for the Script page’s policy.
- final String id — The block’s id, which its places name.
- final String projectKey — The film’s key (projectKeyOf).
- final Object tapGroup — The block card’s tap group, which the frame prompts’ @ lists join.
- static const frames — The places shown whatever they hold, each with the prompt it renders from.
- static const headers — The places whose prompt is their header: the frames’, and the clip’s where its place is shown (§9.3).

`lib/src/character_edit_tab.dart`

function Map<String, String> characterFormSeed(Entity entity) — The text each box of the character form starts with.
function List<FormSectionSpec> characterFormSections(BuildContext context, FormScope scope, FilmProject project) — The sections of a character’s form: who they are, how they look, how they sound, how they behave, who they know, and what a model is told — each with an icon on its title row, so a long form can be read by its shapes…

`lib/src/dormant_field.dart`

class DormantFields — Draws the fields under it dormant (§9.3, the chat page): each text box its words alone until it is clicked.
- const DormantFields({super.key, required super.child}) — Marks [child]’s fields as dormant.
- static bool of(BuildContext context) — Whether [context] is in dormant fields.
typedef typedef DormantSite — Where a dormant field stands, for the log (§9.3): its file, its key and its column, left or right.
function DormantSite? dormantRow(DormantSite? site, String part) — [site]’s row named [part] (a relationship’s character, an epoch’s year), null where [site] is.
typedef typedef DormantEditorBuilder — Draws the live editor on [focusNode], which is null where the field is not dormant: the editor as it has always been.
class DormantField — A field drawn as its text in a box that looks like the field, holding no editable field (§9.3): a click, a tap or focus by keyboard turns it into its [editor] in place, the caret where the person clicked; leaving the…
- const DormantField({ super.key, required this.site, required this.controller, required this.decoration, required this.editor, this.style, this.minL… — Wraps [editor] at [site].
- final DormantSite? site — Null where the field is not dormant; else where it stands.
- final TextEditingController controller — The text the box draws and the editor edits.
- final InputDecoration decoration — The field’s own decoration, the locked look included.
- final DormantEditorBuilder editor — The live editor.
- final TextStyle? style — The field’s text style, as given to its editor.
- final int minLines — The editor’s minimum lines.
- final int maxLines — The editor’s maximum lines; the box clips beyond them.
- final bool tabStop — Whether Tab reaches the box, as it would the editor: not a locked box the editor never let take the focus.
- final Widget? Function(BuildContext context)? suffix — What the editor adds after the decoration’s own suffix (a prose box’s microphone), drawn with the box.
- final bool arrow — Whether the field is a combo box: the box wears its arrow, which opens the field.
- final String? identifier — The box’s semantics identifier, where the editor supplies its own rather than a wrapper around it.
class DormantText — A box’s text laid out by the render object the live editor uses, so that it wraps, and places each chip, as the editor does (§9.3): one line at the editor’s caret gap, its chips given the field’s whole width.
- DormantText({ super.key, required this.span, required this.textScaler, required this.minLines, required this.maxLines, required this.strutStyle, })… — Lays out [span] between [minLines] and [maxLines], with [strutStyle] as the editor’s.
- final InlineSpan span — The box’s text and chips.
- final TextScaler textScaler — The ambient text scale.
- final int minLines — The editor’s minimum lines.
- final int maxLines — The editor’s maximum lines, clipped beyond them.
- final StrutStyle strutStyle — The editor’s forced strut, so a chip does not stretch its line.

`lib/src/draft_saver.dart`

enum SaveState — Where a form’s draft stands with respect to its file.
- values: clean, dirty, saving, failed
class DraftSaver — The autosave behind every entity form: a working copy of the file’s JSON, written a moment after the last change, flushed when the page is left, re-seeded when the file changes underneath.
- DraftSaver({required Entity entity, required this.write, this.projectKey, this.reseed, this.reload, this.delay = const Duration(milliseconds: 700)})
- final Future<void> Function(Entity entity, Map<String, dynamic> json) write — Writes [json] as the new content of [entity]; throws on failure.
- final void Function(Map<String, dynamic> before, Map<String, dynamic> after)? reseed — Updates only boxes whose seeded values this external change replaces.
- final Future<void> Function()? reload — Re-reads the project, for Discard and re-read after a refused write.
- final Duration delay
- Entity get entity
- Map<String, dynamic> get draft
- bool get disposed — Whether the form let this draft go — it moved to another file, or went away: what answers late, as a dialog does, must not change it.
- int get revision — Counts the changes made to [draft].
- SaveState get state
- Object? get error
- bool get hasUnsavedWork
- bool get touched — Whether anything has been written into this draft since it was seeded.
- void setString(String key, String text) — A string field: trimmed, removed when empty.
- bool entityChanged(Entity next) — The form received a new [Entity].
- Future<bool> flush({String reason = 'flush'}) — Writes now when there is something to write.
- Future<void> discardAndReload() — Throws the draft away and re-reads the file: the way out of a refused write when the other change should stand.
class SaveStatus — A failed write’s error, for the top right of a form: a saved, unsaved or saving draft says nothing.
- const SaveStatus({super.key, required this.saver, this.idPrefix = ''})
- final DraftSaver saver
- final String idPrefix — Put before the way out’s identifiers, so two writable columns on one page each name their own (right:).

`lib/src/embedded_form.dart`

variable const Map<EntityType, List<String>> workflowMediaGroups — The places the Workflow tab shows of each type: its named places, and no others (§9.3).
function List<String> workflowBlockGroups(Object? block) — A block’s places on the Workflow tab: its frames and its clip, and its speech where it has a speaker (§9.3).
class MediaFormCard — A version’s media as one card that sits in a list: an entity’s [workflowMediaGroups], each under its Prompt card, or a scene’s blocks, each with its [workflowBlockGroups] — the form’s own state ([FormSide]) and places…
- const MediaFormCard({super.key, required this.project, required this.entity, required this.editable}) — The card of [entity], a version of [project].
- final FilmProject project
- final Entity entity
- final bool editable — Whether the version may be written: the viewer’s own on a writable project (PageAccess).
function ({Widget widget, Map<String, List<String>> groups}) sceneBlockMedia(BuildContext context, FormScope scope, FilmProject project, {required Object ta… — A scene’s blocks in script order, as the Workflow tab’s card and the chat page draw them (§9.3).

`lib/src/entity_creation.dart`

class EntityCreation — How a form asks for a new character or location: the tree’s dialog, which this package may not import, supplied by the page that draws the form ([EntityCreationScope], §9.3).
- Future<VersionStem?> create(BuildContext context, EntityType type, {String? epoch}) — Asks a person for a new [type] entity — a character or a location — and writes its first version as the username in effect; [epoch] is the epoch the dialog offers first where the project declares several.
class EntityCreationScope — Hands the forms under it an [EntityCreation]: a page’s View/Edit, where a scene makes a character or a location in place and keeps it.
- const EntityCreationScope({super.key, required this.creation, required super.child})
- final EntityCreation creation
- static EntityCreation? of(BuildContext context) — The creation the page offers, or null where it offers none.
function String sceneEpochOf(FilmProject project, Map<String, dynamic> scene) — The epoch a scene is set in: its own epoch as written — one the project does not declare is flagged on its form, and is still the scene’s — else the project’s default (Project Specification §8.2).
function String? attachedEpoch(FilmProject project, VersionStem created, String sceneEpoch) — The epoch a new [created] entity joins a scene set in [sceneEpoch] with: its own where it differs and the project still declares it, else none, the entity resolving at the scene’s (§13 item 6).
function Future<String?> createForScene(BuildContext context, FormScope scope, EntityCreation creation, EntityType type, { required String key, required boo… — Makes a [type] entity through [creation] and hands it to [attach] on the scene’s own draft (§9.3), with the epoch it joins with ([attachedEpoch]), answering a sentence where it was made and not put in the scene, else…

`lib/src/entity_data_spec.dart`

variable const String blocksKey — A scene’s script, the key sceneBlocksSections draws and Other attributes never does.
typedef typedef EntityDataSpec — What a file’s data looks like as fields: the one place an entity type decides which form it gets.
function EntityDataSpec entityDataSpec(FilmProject project, Entity entity, {bool? blockRows}) — [blockRows] is the answer a comparison has taken for both its columns ([pairDrawsBlockRows]).
class EntityDataTab — The View/Edit tab: one column of the file’s data, editable when the file is the viewer’s own (§9.3).
- const EntityDataTab({ super.key, required this.project, required this.entity, required this.editable, required this.onFork, this.toolbar, this.lead…
- final FilmProject project
- final Entity entity
- final bool editable
- final VoidCallback onFork
- final Widget Function(BuildContext context, Future<void> Function()? flush)? toolbar
- final Widget? leading — Drawn above the form’s cards ([EntityForm.leading]): a folder’s contents.

`lib/src/entity_file_menu.dart`

class EntityFileMenu — What can be done with the file itself, at the right of View/Edit’s first card title (§9.3).
- const EntityFileMenu({ super.key, required this.project, required this.entity, required this.actions, required this.canEdit, this.canRunPlugins = f…
- final FilmProject project
- final Entity entity
- final WriteActions actions
- final bool canEdit — The file is the viewer’s own and the project can be written — the same rule the tab title follows (§17).
- final bool canRunPlugins — A plug-in may be run on the file (PageAccess.canRunPlugins).
- final Future<void> Function()? flush — Writes the form’s pending draft.

`lib/src/entity_form.dart`

class FormPane — One presentation of an entity file’s data, in two modes (§9.3): Edit on a version the viewer may write, where a [DraftSaver] carries every change, and view on any other, drawn locked.
- FormPane(BuildContext context, this.scope, FormSections build)
- final FormScope scope
- final List<FormSectionSpec> sections
- Widget? cell(BuildContext context, String sectionId, String fieldId) — Builds this pane’s field with its own scope, version and field identifier.
- FormSectionSpec? section(String id) — This pane’s own section of that id, or null where this column has none.
- FormFieldSpec? spec(String sectionId, String fieldId) — This pane’s field of that section, for a label the other column borrows when it has none of its own.
class FormProseValue — Publishes a rendered prose field’s committed canonical value for recorder sampling.
- const FormProseValue({super.key, required this.identifier, required this.controller, required this.child}) — Binds the source reader to the actual rendered identifier and controller.
- final String identifier — The consumer’s version-qualified field identifier.
- final ProseController controller — The rendered field’s controller, whose provisional source is excluded from sampling.
- final Widget child — The existing editor subtree, with its semantics and focus behavior preserved.
class FormScope — What a field builder is given.
- const FormScope({ required this.entity, required this.draft, required this.enabled, required this.singleColumn, required this.box, required this.pr… — Supplies one column’s controllers, draft, write rules and redraw callback.
- final Entity entity — The file the form is showing.
- final Map<String, dynamic> draft — The working copy every field reads, so two changes inside one save window accumulate instead of the second overwriting the first.
- final bool enabled — Whether the inputs accept anything.
- final bool singleColumn — One field per row whatever the width allows: a narrow pane (§9.1) and both Compare columns.
- final TextEditingController Function(String key) box — The seeded controller for a key, retaining its prose upgrade once requested.
- final ProseController Function(String key, {String? prompt}) proseBox — Upgrades a fitting prose editor’s seeded box while preserving its exact source and mode.
- final VoidCallback refresh — Redraws without touching the draft, for an error text that depends on what is typed rather than on what is saved.
- final DraftSaver? saver — Null in view mode, so a field cannot write what it must not.
- final AssistantDraft Function()? assistantDraft — Captures the current draft, or a View form’s entity as read, only on an assistant gesture; absent in Compare.
- final String idPrefix — Put before the identifiers of this column’s controls that name no version — its save status’s way out, the epochs’ rows — so two writable columns on one page each name their own (right: in Compare).
- final String? idNamespace — Put before every identifier this column’s fields and controls produce, the version-qualified ones included, where one page draws several comparisons (compare[<n>].left, the session’s review, §9.3); null on every…
- final bool picked — Whether this column holds the viewer’s pick ([FilmProject.isPickOf]); its cells wear no border for it (§9.3).
- final ProjectMentionCandidates candidates — The film’s mention names and pictures, shared by the form’s prose boxes and a scene’s script.
- final int candidatesRevision — Changes exactly when the list of [candidates] or of a [promptCandidates] changes: a box the form did not make re-projects then.
- final PromptMentionCandidates Function(String kind) promptCandidates — The form’s one @ source for prompts of the writers’ kind (§9.8), bound to the draft as the form is: a frame’s and a clip’s prompt in the scene’s script take theirs here.
- String fieldIdOf(String key, {String? pairId}) — The existing global field identifier, shared by semantics, dictation and field assistance; under [idNamespace] where there is one.
- final void Function(void Function(Map<String, dynamic> draft) apply) copy — A copy-left write (§13.3): one change through the autosave, and then the boxes whose value the copy changed take their new text.
- final AssistantShortcuts? shortcuts — What the active assistant’s catalog offers on this form’s fields and sections, for the AI icons (§6.11a); null where the form may not ask the assistant or the assistant is not available.
- final bool comparing — Whether this is a column of a comparison, which pairs a section the form draws elsewhere as its own rows (a prompt above its place, §9.3): the media card draws no Prompt card there.
- final bool dormant — Whether this form’s text boxes are drawn dormant ([DormantField]): under [DormantFields], the chat page’s (§9.3).
- DormantSite? dormantSite(String key) — The dormant [DormantField] site of the field at [key], null where this form’s boxes are not dormant.
- void change(void Function(Map<String, dynamic> draft) apply, {String? key}) — A field’s change, the form not drawn again for it, so typing costs no build per letter.
- void setString(String key, String text) — A string box’s change: trimmed, removed when empty, the form not drawn again for it (see [change]).
- Widget? dictate(String key, { required ValueChanged<String> onChanged, List<TextInputFormatter> formatters = const [], int? maxLength, bool writabl… — The controls at the right of the box at [key]: the microphone (Software Specification §9.6), then the AI icon where the catalog offers an action on this field (§6.11a); null where there is neither.
- InputDecoration lock(BuildContext context, InputDecoration input, {bool locked = false}) — The decoration a field hands to its input: [lockedDecoration] where the form or the field is locked; in a comparison its label stands above the box and its hint is not drawn, so that an empty value reads as empty (§9.3).
class ComparingFields — Marks a comparison’s fields (§9.3): a box that decorates itself floats its label and leaves an empty box empty.
- const ComparingFields({super.key, required super.child}) — Marks [child] as a comparison’s fields.
- static bool of(BuildContext context) — Whether [context] is in a comparison’s fields.
- static InputDecoration compared(InputDecoration input) — [input] as a comparison draws it: the label above the box, no hint.
- static InputDecoration decorate(BuildContext context, InputDecoration input) — [input] as [context] draws it: [compared] in a comparison’s fields, else as given.
- static InputDecorationThemeData pullDown(BuildContext context, InputDecorationThemeData theme) — A pull-down’s [theme] as [context] draws it: its label above the box in a comparison’s fields.
function InputDecoration lockedDecoration(BuildContext context, InputDecoration input) — [input] as a locked box wears it.
class FormFieldSpec — One input.
- const FormFieldSpec({required this.keys, required this.build, this.width, this.id, this.label, this.copy, this.set, this.applies = false})
- final List<String> keys
- final bool applies — Whether the field edits one string, so the assistant’s Apply may write it (§6.11a): only a text box says so.
- final void Function(FormScope scope, String text)? set — Types text into this field as its own onChanged does.
- final RowCopy? copy — What copy-left writes for this row (§13.3), where the keys the field owns are not it.
- RowCopy get rowCopy — [copy], or the keys this field owns.
- final String? id — What pairs this field with the other column’s (§13.3).
- final String? label — The field’s own label, so the other column can name a row it does not have.
- String get pairId — The id two columns pair on.
- final double? width — The preferred width in a wrapping row, in logical pixels; or, at 1 and below, a share of the row on a grid of four columns (0.25 a column, 0.5 two, 0.75 three), so boxes of a section line up with each other and…
- final Widget Function(BuildContext context, FormScope scope) build
class FormSectionSpec
- const FormSectionSpec({ required this.title, required this.fields, this.id, this.icon, this.action, this.subtitle, this.folded = false, this.body,…
- final String title
- final String? subtitle — A line under the title saying what the card holds (Epochs’ periods), which the form draws and a comparison’s columns do not.
- final IconData? icon — Drawn on the card’s title row, before the title (a face beside Features).
- final Widget Function(BuildContext context, FormScope scope)? action — A control on the card’s title row, after the title, which the form draws and a comparison’s columns do not.
- final String? id — What pairs this section with the other column’s.
- final List<FormFieldSpec> fields
- final bool folded — Whether the form folds it away (Advanced treatment): a part of Other where the form folds that, else a card of its own, closed on every entry to a version; a comparison’s columns show it as any other.
- final Widget Function(BuildContext context, FormScope scope, List<Widget> fields)? body — The section’s whole card on the form, in place of its own [SectionCard]: given the built [fields] — each with its identifier and the assistant’s wrapper — it draws its own title, frame and collapse (a prompt’s card, §…
- final bool compareOnly — Whether the form draws the section elsewhere, not as a card of its own: a prompt whose card stands above its place in the media card (§9.3).
- String get pairId
typedef typedef FormSections — Builds the sections for one file: the only place an entity type is named.
function void setRequiredName(FormScope scope, String text) — A name is required (§7): an empty box is an inline error, which the box draws from its own text, not a removal.
typedef typedef FormSeed — The text each box starts with, by key.
class EntityForm — Renders [sections] for [entity] — with the autosave when [editable], locked otherwise.
- const EntityForm({ super.key, required this.project, required this.entity, required this.editable, required this.seed, required this.sections, this…
- final FilmProject project
- final Entity entity
- final bool foldsOther — Whether the keys no field names and the file’s own facts fold into one Other, closed on every entry to a version (§9.3), rather than standing as the Other attributes and File cards.
- final Widget? leading — Drawn above the form’s cards and scrolled with them: what a page shows of the file that is not a field.
- final bool editable — The file is the viewer’s own and the project can be written.
- final FormSeed seed
- final FormSections sections
- final bool singleColumn
- final bool acceptsInput — Whether the fields take typing at all.
- final EdgeInsets padding
- final Set<String> hiddenKeys — Keys the page shows somewhere else and the form must not repeat — a scene’s blocks, which the Script tab draws.
- final VoidCallback? onFork — Offered by the banner an official file raises; null hides it.
- final Widget Function(BuildContext context, Future<void> Function()? flush)? toolbar — Built into the header row beside the save status.
- static const Duration saveDelay — How long after the last change the file is written.
class FormSide — The state a column of fields needs and nothing else: the draft, the text controllers, and the scope they make.
- const FormSide({ super.key, required this.project, required this.entity, required this.editable, required this.seed, required this.sections, requir…
- final FilmProject project
- final Entity entity
- final bool editable
- final String idPrefix — [FormScope.idPrefix].
- final String? idNamespace — [FormScope.idNamespace]: where it is given, it is the controls’ [idPrefix] too.
- final bool picked — [FormScope.picked].
- final bool acceptsInput
- final bool singleColumn
- final FormSeed seed
- final bool allowAssistant — Whether this is a normal editable form that may expose a field assistant, never Compare by default.
- final bool comparing — Whether this side is a column of a comparison ([FormScope.comparing]).
- final FormSections sections — The sections this side shows, for the registry to find a field’s own setter by key (§7.1).
- final Widget Function(BuildContext context, FormScope scope) builder
class AbsentCell — Where the other column has a key and this one does not (§13.3).
- const AbsentCell({super.key, required this.label, this.tooltip})
- final String label
- final String? tooltip
class FormPullDown — A pull-down that is the height of the boxes beside it.
- const FormPullDown({super.key, required this.child})
- final Widget child
class LockedRow — One value of a file the reader may not change: its label above it, on the ground every locked field wears (§9.3).
- const LockedRow({super.key, required this.label, required this.content, this.tooltip})
- final String label
- final Widget content
- final String? tooltip — The file’s own key, on the label, where the label translates it.
class LockedValue — The value of a choice the reader may not change, drawn as the box a pull-down leaves behind.
- const LockedValue({ super.key, required this.label, this.text = '', this.content, this.icon, this.helper, this.tooltip, })
- final String label
- final String text
- final Widget? content — Shown instead of [text], for a value that is rendered rather than written out.
- final Widget? icon
- final String? helper
- final String? tooltip — The file’s own key, on the label, where the label is a translation of it — as an attribute row does.
function List<Widget> sectionFields(BuildContext context, FormSectionSpec section, FormScope scope) — Each of [section]’s fields as the form draws it: under the identifier an agent addresses it by — the file and the id the field pairs on (pairId, the name Compare’s rows and FieldRegistry use) — and, where the assi…
class AssistantShortcuts — What the active assistant’s catalog offers on a form (§6.11a): the first action of a field’s own, and the first of a form section’s, by the form’s section and pair ids, once [index] has read the sections; the icons’ t…
- AssistantShortcuts({required this.tag, required this.catalog, required this.type}) — What [tag]’s [catalog] offers on a form of the entity type [type].
- final String tag — The active assistant’s package tag, which names its strings.
- final AssistantCatalog catalog — The active assistant’s catalog, loaded.
- final String type — The form’s entity type prefix: the catalog’s section the form’s actions are under.
- void index(List<FormSectionSpec> sections) — Reads which section each field is in; the form calls it once its sections are built.
- AssistantAction? onField(String pairId) — The first action the catalog offers on the field [pairId] itself, or null.
- AssistantAction? onSection(String pairId) — The first action the catalog offers on every field of the form section [pairId], or null.
- String label(AssistantAction action) — [action]’s label in the package’s strings, else its id.
class OfficialEditBanner — §13.2: editing what official names changes what everyone sees.
- const OfficialEditBanner({super.key, this.onFork})
- final VoidCallback? onFork — Forks the version the banner warns about: the page’s own on the data tab, the left column in Compare.

`lib/src/epochs_editor.dart`

class EpochsEditor — The project’s epochs (§8.2) as an editable, reorderable list of labels and years.
- const EpochsEditor({ super.key, required this.epochs, required this.usage, required this.onChanged, this.idPrefix = '', this.enabled = true, this.o…
- final DormantSite? site — The field’s dormant site, null where its boxes are live (§9.3).
- final List<EpochDeclaration> epochs
- final Map<String, int> usage — How many entity files carry each epoch token.
- final ValueChanged<List<EpochDeclaration>> onChanged
- final bool enabled
- final String idPrefix — [FormScope.idPrefix], put before every row’s identifiers and Add an epoch’s.
- final Future<String?> Function(String label, int? year)? onAdd — Declares an epoch with a label and an optional year, written at once rather than into the draft.
- final String? addUnavailable — Why Add epoch is disabled, as its tooltip.
- final String? addNotice — What adding does beyond the list, said in the dialog.

`lib/src/folder_edit_tab.dart`

variable const PathBoxes folderBoxes — Every box of the folder’s form on a path, and what each holds.
function Map<String, String> folderFormSeed(Entity entity) — The text each box of the folder’s form starts with.
function List<FormSectionSpec> folderFormSections(BuildContext context, FormScope scope, FilmProject project) — A folder’s form (Project Specification §10.1): Name, Kind, Synopsis and Notes, its pictures, and the one thing a folder passes on, its visual treatment (§8.7), with what it inherits.

`lib/src/form_fields.dart`

typedef typedef PathBoxes — The boxes of a form that owns the keys of an open object (§9.3) — a character’s appearance, a location’s geography — one dotted path each.
variable const Set<String> literalFormPaths — Full paths whose text is literal rather than prose; a plug-in’s paths are literal by their prefix ([isLiteralFormPath]).
function bool isLiteralFormPath(String path) — Keeps identifiers and dynamic plug-in text outside the shared prose controller.
function String formBoxSource(TextEditingController box) — Reads canonical prose source while leaving ordinary literal controllers untouched.
variable const int kHelperMaxLines — How many lines a helper text may take under a box (§6: helper and error texts wrap).
function Map<String, String> pathBoxesSeed(Entity entity, PathBoxes boxes) — The text every box of [boxes] starts with, for a form’s seed.
function void Function(FormScope scope, String text) pathBoxSetter(String path, PathValue kind) — One box’s setter: the same function its onChanged runs.
function String? promptOfWordsPath(String path) — The dotted path of the prompt whose words [path] names (prompts.reference for prompts.reference.positive, at any depth), or null for any other path.
function List<FormFieldSpec> promptFields(AppLocalizations l10n, String path, {required String target}) — The boxes of the prompt at [path] (§9.0): its positive and its negative, each written through [pathBoxSetter], which takes away the prompt’s plugin where a person changes its words.
function List<WriterToken> promptWriterTokens(AppLocalizations l10n, FilmProject project, Entity document, String kind, {required Author? viewer}) — The media tokens a writer of [kind] is handed for [document] (revision 13): each as written, named as its chip is.
function FormSectionSpec promptSection(AppLocalizations l10n, {required String id, required String path, required String target, bool compareOnly = false}) — The section of the prompt at [path] (§9.3): [promptFields] for a comparison, and on the form the Prompt card of the writers’ [target] around them — written through the form’s draft where the form takes input, read-onl…
function void setAliases(FormScope scope, String text) — aliases (A.1, A.3): every name a script might use, typed as a list separated by commas, as a script’s cue names are written.
function bool aliasesFit(Map<String, dynamic> json) — Whether aliases is absent or a list of strings: anything else is not the box’s to rewrite.
function String aliasesText(Entity entity) — The seed of [aliasesField].
function FormFieldSpec aliasesField() — The aliases box of a character or a location.
typedef typedef BoxCheck — Checks whether canonical text is a value the file may hold and supplies its refusal sentence.
function FormFieldSpec pathBoxField(PathBoxes boxes, String path, { required String label, double? width, bool multiline = false, String? hint, String? help… — A text, number or lines box on [path], labelled [label], preserving its shape and source rules.
function FormFieldSpec pathChoiceField(String path, { required String label, required List<String> values, required String Function(String token) labelOf, I… — A word from a short vocabulary (A.1’s voice.pitch, A.3’s time_of_day) as a row of chips.
class ShapeLocked — A locked field is read-only and not disabled, with the reason under it: locked, legible, and changed with Edit JSON.
- const ShapeLocked({super.key, required this.label, required this.value})
- final String label
- final Object? value
function FormFieldSpec relationshipsField({required String label}) — A character’s relationships (A.1: { character, relation } each) as rows of two boxes with a remove button, under an Add relationship.
function FormFieldSpec nameField({required Widget icon, String? label, bool applies = false}) — A file’s Name, the box every form starts with.
function void Function(FormScope scope, String text) tokenSetter(String key, List<String> Function() choices) — A key that holds one token out of [choices], as an agent types it.
function FormFieldSpec tokenChoiceField({ required String key, required String label, required IconData icon, required List<String> Function() choices, requ… — One token out of a list as a pull-down with a none entry that removes the key: a scene’s location and epoch, a location’s within (§9.3), a project’s kind (§8.1).

`lib/src/generic_view_tab.dart`

function bool showsBlockRowsIn(EntityType type, Map<String, dynamic> json) — Whether this document draws a row per block rather than a blocks value: a scene whose blocks holds blocks.
function bool pairDrawsBlockRows(EntityType type, Map<String, dynamic> left, Map<String, dynamic> right) — Whether a comparison of these two documents draws block rows.
function bool showsBlockRows(Entity entity)
function Set<String> genericSkipIn(EntityType type, Map<String, dynamic> json) — What a generic page never shows as a value row.
function Set<String> genericSkip(Entity entity)
function Map<String, String> genericFormSeed(Entity entity) — No box starts with anything.
function List<FormSectionSpec> genericFormSections(BuildContext context, FormScope scope, {bool? blockRows}) — [blockRows] overrides this document’s own answer about whether it draws block rows, so a comparison can give both columns the one answer ([pairDrawsBlockRows]); null asks the document alone.
function List<FormSectionSpec> blockRowsSections(BuildContext context, FormScope scope, {required bool drawsBlocks}) — A scene’s blocks as one read-only row each, in a section of their own.
function List<FormSectionSpec> sceneBlocksSections(BuildContext context, FormScope scope, FilmProject project, { bool? blockRows, }) — What a scene’s form shows of blocks: the Dialog and actions card as the editor on the page, a row per block in a comparison.
function String blockLine(Map<String, dynamic> block, {String? beats, String? subtitles}) — One block as a line, as a comparison’s row shows it, its beats and its subtitles counted after it.

`lib/src/guard_line.dart`

class GuardLine — One red line of development mode (§9.5).
- const GuardLine({super.key, required this.text, this.actionLabel, this.onAction, this.identifier})
- final String text
- final String? identifier — The semantics identifier of the action, for an agent; null where the line has no action or the page gives none.
- final String? actionLabel
- final VoidCallback? onAction
function String guardNoticeText(AppLocalizations l10n, GuardNotice notice, FilmProject project, Entity entity, Author? viewer) — The sentence of one [GuardNotice], for the page’s red line and for the message a governed write shows (§9.5).

`lib/src/import_review_dialog.dart`

enum ImportReviewResult — How a review closed.
- values: applied, discarded, later, dismissed
function Future<ImportReviewResult> showImportReview(BuildContext context, String id) — Shows the review of the proposal [id] until it closes, and answers how.
class ImportReviewDialog — The review of the import proposal [id], as ImportProposals holds it; closes itself when the proposal goes.
- const ImportReviewDialog({super.key, required this.id})
- final String id — The proposal’s id in ImportProposals.

`lib/src/json_editor_dialog.dart`

function Future<void> showJsonEditor(BuildContext context, { required Entity entity, required WriteActions actions, bool official = false, }) — Edits the file’s JSON by hand — the way to change anything the forms do not cover.
class JsonDocumentEditor — The JSON editor’s presentation over a plain map: a tree whose values are changed by tapping them, or the whole text.
- const JsonDocumentEditor({ super.key, required this.rootName, required this.initial, required this.identifier, required this.config, required this.… — The editor over [initial], its root named [rootName].
- final String rootName — The root’s name, the file’s stem: the first segment of every path the tree names.
- final Map<String, dynamic> initial — The document as it opens; the editor works on a copy.
- final String identifier — The prefix of the editor’s semantics identifiers.
- final JsonTreeConfig config — How the tree opens.
- final ValueChanged<String> onText — The text typed, which is not read until the tree is asked for again.
- final void Function(Map<String, dynamic> doc, String text, {required bool applied}) onDocument — A document the editor holds: a value [applied] in the tree, or the text read back into the tree.
- final ValueChanged<String> onRefused — The text could not be read back into the tree: why, as a sentence.
- final bool busy — While true, nothing is changed and the mode is held.
- final String? error — What to say under the document, in the error’s colour.
- final Widget? errorAction — What [error] offers to do about it.
- final Widget? notice — A line under the mode switch.
- final List<String> reveal — The dotted paths, under the root, opened in the tree whenever it is drawn again.
function Map<String, List<Object>> jsonTreeAccessors(Map<String, dynamic> doc, String rootName) — Every path the tree names (root.a.b[0], the tree’s own spelling), with the keys and indexes that reach it in [doc].
function void setJsonAt(Map<String, dynamic> doc, List<Object> route, Object? value) — Writes [value] at [route] inside [doc].
function String jsonEncodeValue(Object? value) — A scalar as the value box shows it: 12, true, null.
function Object? parseTypedValue(String text) — What was typed where a number, a boolean or null stood: that kind again when it reads as one, else the text itself.

`lib/src/location_edit_tab.dart`

function Map<String, String> locationFormSeed(Entity entity) — The text each box of the location form starts with.
function List<String> withinChoices(FilmProject project, String self, {required Author? viewer}) — The other locations of [project] a location may lie within (§9.3, the Project Specification’s within).
function List<FormSectionSpec> locationFormSections(BuildContext context, FormScope scope, FilmProject project) — The sections of a location’s form, each with an icon on its title row.

`lib/src/media_section.dart`

variable const String outfitSheetsGroup — An outfit’s sheets: the place its pictures, and the composite sheet rendered from its character, go.
variable const String propSheetsGroup — A prop’s sheets: the place its pictures from its sides go.
function FormSectionSpec referenceMediaSection(BuildContext context, FormScope scope, FilmProject project, {Map<String, FormSectionSpec> prompts = const {},… — The media card of a version: the card below General on a character’s, a location’s, an outfit’s and a prop’s form, and the card above the visual treatment on the project file’s and a folder’s — the same card in both…
function bool sheetPickFits(Map<String, dynamic> draft) — Whether picks.sheet holds what [sheetPickField] can show: nothing, a reference, or a list of references.
variable const String sheetPickPath — The path of the chosen sheet (Project Specification A.1, A.2, A.3): a reference, or a list of them.
function FormFieldSpec sheetPickField(BuildContext context, FilmProject project, String group) — picks.sheet as chips over the version’s own [group] (outfit_sheets, prop_sheets), each named as its tile is.
class MediaCard — One version’s media as places: the type’s places of [entityMediaPlaces], always and in their order, and a preview no entry names; a group the file holds that the type does not list is kept and not shown (§9.0).
- const MediaCard({super.key, required this.scope, required this.project, this.prompts = const {}, this.groups})
- final FormScope scope
- final FilmProject project
- final Map<String, FormSectionSpec> prompts — The form’s prompt sections by kind (reference, sheet, voice); none draws no card.
- final List<String>? groups — The places drawn, null for every place of the type; given (the Workflow tab’s named places), the type’s other places and a loose preview are not drawn.

`lib/src/outfit_edit_tab.dart`

function Map<String, String> outfitFormSeed(Entity entity) — The text each box of the outfit form starts with.
function List<FormSectionSpec> outfitFormSections(BuildContext context, FormScope scope, FilmProject project) — The sections of an outfit’s form (A.2): what it is, its pictures, the garments, what goes with them, and what a model is told.
function FormFieldSpec garmentsField({required String label}) — An outfit’s garments (A.2: { item, color, material, fit, pattern, condition, notes } each) as one group of boxes per garment with a remove button, under an Add garment.
class GarmentsEditor — The garments of [garmentsField].
- const GarmentsEditor({ super.key, required this.stem, required this.garments, required this.enabled, required this.onChanged, }) — The rows of [garments], written through [onChanged] where [enabled].
- final String stem — The file’s stem, in the identifiers: Compare draws two of these.
- final List<Map<String, dynamic>> garments — The garments the draft holds, each an object (A.2), in their order.
- final bool enabled — Whether the version may be written: else every box is locked and nothing is added or removed.
- final ValueChanged<List<Map<String, dynamic>>> onChanged — Every garment on screen, empty ones included; the caller drops what holds nothing.

`lib/src/plugin_field_widgets.dart`

function bool? pluginSwitchValue(String text) — true or false, as an agent types a switch; anything else is null and writes nothing.
function String? pluginChoiceToken(PluginField field, String text) — One of [field]’s tokens, or an empty string to remove the value.
function String pluginChoiceLabel(PluginField field, String? token) — The words of [field]’s choice [token]: its label, else the token itself.
function String? pluginServerValue(String text) — [text] as a server field holds it.
function bool pluginServerIsExposed(String text) — Whether [text] is a plain http address at an address that is certainly public, which is saved with a warning and not refused (warn, don’t enforce).
class PluginSwitchField — A plug-in’s boolean field: its label and help beside a switch.
- const PluginSwitchField({super.key, required this.field, required this.value, required this.onChanged})
- final PluginField field
- final bool value
- final ValueChanged<bool>? onChanged
class PluginChoiceField — A plug-in’s choice or model field.
- const PluginChoiceField({super.key, required this.field, required this.current, required this.onSelected})
- final PluginField field
- final String? current — The token chosen, or null for none.
- final ValueChanged<String>? onSelected
class PluginTextBox — A plug-in’s text, multi-line text or number box on a [controller] the caller keeps.
- const PluginTextBox({super.key, required this.field, required this.controller, required this.onChanged})
- final PluginField field
- final TextEditingController controller
- final ValueChanged<String> onChanged
function String? pluginNumberRefusal(PluginField field, String text) — Why [text] typed into [field]’s number box is refused — notNumber, belowMin, aboveMax — or null where it is kept: out of the setting’s range saves nothing, as text that is no number does (§6.11).
class PluginServerBox — A plug-in’s server field: one line, a URL keyboard, and the address the person types.
- const PluginServerBox({super.key, required this.field, required this.controller, required this.onChanged})
- final PluginField field
- final TextEditingController controller
- final ValueChanged<String> onChanged
class PluginProgramBox — A person-chosen executable path with an explicit acceptance of a discovered program.
- const PluginProgramBox({super.key, required this.field, required this.controller, required this.onChanged, required this.onUse}) — Draws the stored path and a separate choice for the executable found on PATH.
- final PluginField field — The program’s label, found path and stored path’s executable state.
- final TextEditingController controller — The path being typed by the person.
- final ValueChanged<String> onChanged — Saves a typed path through the page’s ordinary setting setter.
- final ValueChanged<String> onUse — Accepts the found executable through the same setting setter.

`lib/src/plugin_hook_dialog.dart`

function List<PluginSummary> pluginsTransforming(EntityType type) — The enabled plug-ins whose transform applies to [type], as the file menu’s Plugins… lists them.
function Future<void> showPluginHookDialog(BuildContext context, {required Entity entity}) — Plugins… on an entity page (§9.3).

`lib/src/plugin_sections.dart`

function List<PluginSection> pluginSectionsFor(EntityType type) — The plug-ins’ cards on an entity’s page and the project’s: each enabled plug-in’s entitySettings for the type, drawn by the app’s own fields after the type’s own sections.
function String pluginFieldPath(PluginSection section, PluginField field) — The dotted path of [field] in [section].
function PathBoxes pluginBoxes(List<PluginSection> sections) — The boxes the sections of [type] take, for the form’s seed.
function FormSeed withPluginSeed(FormSeed seed, List<PluginSection> sections) — A form’s seed with the plug-ins’ boxes added to [seed]’s.
function List<PluginSection> drawnPluginSections(List<PluginSection> sections) — [sections] as a page draws them: no server field, and no section left with none.
function List<FormSectionSpec> pluginFormSections(BuildContext context, FormScope scope, List<PluginSection> sections) — The cards of [sections], one per plug-in, as [drawnPluginSections] leaves them.

`lib/src/project_edit_tab.dart`

function Map<String, String> projectFormSeed(Entity entity) — The text each box of the project form starts with.
variable const subtitleFonts — The faces bundled for subtitles (assets/fonts/), each as format.subtitles.font names it.
function List<FormSectionSpec> projectFormSections(BuildContext context, FormScope scope, FilmProject project)

`lib/src/prop_edit_tab.dart`

function Map<String, String> propFormSeed(Entity entity) — The text each box of the prop form starts with.
function List<FormSectionSpec> propFormSections(BuildContext context, FormScope scope, FilmProject project) — The sections of a prop’s form (A.3): what it is, its pictures, how it is handled and heard, and what a model is told.
function FormFieldSpec heroField({required String label}) — A prop’s hero (A.3: seen close, needs a strong reference) as a switch, a boolean in the file.

`lib/src/row_editors.dart`

mixin LocalProse — The mention context of the prose boxes a row or a dialog owns in its own state rather than in the form’s seed (§9.8).
- ProseController ownProse(String source, {bool readOnly = false}) — A prose controller holding [source], disposed with this state.
- void watchMentions() — Follows another project or viewer without touching the boxes’ source; called from build.
function Widget localProseBox({ required ProseController controller, required String identifier, required InputDecoration decoration, required ValueChanged<… — A prose box of a row or a dialog: [controller] in the prose editor under [identifier], the microphone after it where it can be typed into (§9.6), and its committed source sampled as a form field’s is.
function Widget twoPartRow({ required Widget first, Widget? second, Widget? third, Widget? remove, int firstFlex = 1, int secondFlex = 1, bool singleColumn… — The layout both editors’ rows use: two parts — or three, [third] beside [second] — that share a row while there is room and stack when there is not (§9.1), with [remove] at the end however the parts are laid out.
class RelationshipsEditor — The rows of [relationshipsField].
- const RelationshipsEditor({ super.key, required this.stem, required this.relationships, required this.enabled, required this.label, required this.e…
- final DormantSite? site — The field’s dormant site, null where its boxes are live (§9.3).
- final String stem — The file’s stem, in the identifiers: Compare draws two of these.
- final List<Map<String, dynamic>> relationships
- final bool enabled
- final String label
- final String emptyText
- final ValueChanged<List<Map<String, dynamic>>> onChanged — Every row on screen, empty ones included; the caller drops what holds nothing.
class PickerThumb — An entity’s picture in a picker’s entry (§9.3): a [size] square, decoded at the size it is drawn, the type’s icon where there is none or it cannot be drawn.
- const PickerThumb(this.location, {super.key, required this.type, this.size = 40})
- static const double itemHeight — The height of a picker’s entry that carries a picture.
- final MediaLocation? location
- final EntityType type
- final double size
class MenuLog — A pull-down’s menu controller that logs each use of it (the logging rule): <event>.opened as the menu opens, then one outcome, with ms from the opening.
- MenuLog(this.event)
- final String event — The events’ prefix, such as script.speaker.
- Map<String, Object?> data — What the opening is logged with; the pull-down sets it as it is built.
- void end(String outcome, Map<String, Object?> data) — The menu’s outcome — chosen, unchanged, refused — with [data].
typedef typedef CastOutfit — An outfit a cast entry may wear: its short name, its name in use and its picture.
class CastEditor — The rows of a scene’s Characters: one per cast entry — the character’s name in use and short name, its own epoch where the project declares several, its outfit where it has two or more there, and a remove button.
- const CastEditor({ super.key, required this.stem, required this.cast, required this.enabled, required this.singleColumn, required this.epochs, requ…
- final List<CastOutfit> Function(Map<String, dynamic> entry)? outfitsOf — The outfits an entry may wear: its character’s at its epoch, else the scene’s.
- final MediaLocation? Function(String tag)? pictureOf — A character’s picture in the menu, by its short name; none drawn where null.
- final VoidCallback? onCreate — Makes a character and puts it in the scene; null where the page offers no creation (Compare’s columns).
- final String stem — The file’s stem, in the identifiers: Compare draws two of these.
- final List<Map<String, dynamic>> cast
- final bool enabled
- final bool singleColumn
- final List<String> epochs — The project’s epochs where it declares more than one, else none: a row then has no epoch of its own to choose.
- final String Function(String tag) epochName
- final String Function(String tag) nameOf
- final bool Function(String tag) isKnown
- final List<String> toAdd — The project’s characters not in the scene yet.
- final bool hasCharacters — Whether the project has any character at all, for the reason an empty menu gives.
- final ValueChanged<List<Map<String, dynamic>>> onChanged

`lib/src/scene_edit_tab.dart`

variable const PathBoxes sceneBoxes — Every box of the scene’s form on a path, and what each holds.
function Map<String, String> sceneFormSeed(Entity entity) — The text each box of the scene’s form starts with.
function List<String> sceneLocationChoices(FilmProject project, {required Author? viewer}) — The short names of [project]’s locations, in the tree’s order, but those in [viewer]’s recycle bin and those wholly discarded (§7).
function List<String> sceneCharacterChoices(FilmProject project, {required Author? viewer}) — The short names of [project]’s characters, in the tree’s order, but those in [viewer]’s recycle bin and those wholly discarded (§7).
function MediaLocation? Function(String tag) scenePictureOf(FilmProject project, Map<String, dynamic> draft, Author? viewer) — A character’s picture in a scene’s pickers, by its short name: at the scene’s epoch, as [viewer] sees it (§9.3).
function List<FormSectionSpec> sceneFormSections(BuildContext context, FormScope scope, FilmProject project) — A scene’s form (Project Specification §10.2): a scene is a series of events at a time and a place, so it names one location and one epoch and lists its characters.

`lib/src/script_editor.dart`

typedef typedef ScriptChange — One edit of a scene’s blocks, handed to the scene’s one draft (Software Specification §9.3).
typedef typedef SpeakerPicture — The picture a speaker’s mark draws: the character’s [stem], the entry’s [reference] and where its bytes are.
typedef typedef SpeakerMark — What a speaker’s mark shows, from one resolution of the speaker: the [name] and the [picture], if any.
class ScriptEditor — A scene’s blocks, edited where they are: the Edit tab’s Dialog and actions card (Software Specification §9.3).
- const ScriptEditor({ super.key, required this.stem, required this.draft, required this.enabled, required this.characters, required this.nameOf, req… — The editor of [draft]’s blocks.
- final MediaLocation? Function(String tag)? pictureOf — A speaker’s picture in the pull-down, by short name; none drawn where null.
- final SpeakerMark Function(String tag)? speakerMarkOf — A speaker’s mark beside a condensed dialogue block, by short name, its name and picture resolved once; without it, [nameOf] and the character’s icon.
- final String stem — The file’s stem: the identifiers’ and the registry’s (§7.1).
- final Map<String, dynamic> draft — The draft whose blocks this edits: the form’s own working copy, read again at every build.
- final bool enabled — Whether the blocks may be changed: the form’s FormScope.enabled.
- final List<String> characters — Every character of the project, by short name: the speaker pull-down’s second group.
- final String Function(String tag) nameOf — The name a speaker is shown by.
- final ScriptChange onChange — Every change, through the scene’s draft.
- final void Function(int index)? onMove — Opens Move to scene… for the block at a position; null disables the item, saying [moveUnavailable].
- final String? moveUnavailable — Why Move to scene… is disabled, where [onMove] is null.
- final bool singleColumn — One field a row: below Breakpoints.singleColumn of pane, and in a narrow column.
- final MentionCandidates? candidates — The project-backed mention names and pictures the script’s prose fields share, one source updated in place.
- final int candidatesRevision — Changes exactly when [candidates]’ list or a [promptCandidates]’ changes: every prose box made re-projects then, never on another build.
- final PromptMentionCandidates Function(String kind)? promptCandidates — The form’s @ source of a frame’s or a clip’s prompt, by the writers’ kind (§9.8); without one the prompt’s box offers nothing.
- final bool projectWritable — Whether the project may be written at all, which an empty locked card’s words follow: a fork where it may.
- final String? projectKey — The film’s key (projectKeyOf), which a block’s media places name their insertions by; null draws none.
- final Future<void> Function(String reference)? onDeleteTake — The page’s door once a block’s media entry is flagged deleted: it settles the draft, then asks the state.
- final Entity? entity — The scene’s file, which a block’s frame prompts are written in; null draws no frame prompt.
- final DraftSaver? binding — The page’s draft, which a frame prompt’s Generate settles and writes through; null where the blocks are read-only.
variable final scriptEditorCensus — The script editor’s work, counted for the keystroke’s census test.

`lib/src/script_move.dart`

function Future<void> showMoveBlockDialog(BuildContext context, { required FilmProject project, required Entity scene, required String blockId, required Dra… — Opens Move to scene… for the block [blockId] of [scene], whose draft [saver] holds.
class MoveBlockDialog — The dialog of Move to scene…: the film’s other scenes in script order, and the move.
- const MoveBlockDialog({ super.key, required this.project, required this.scene, required this.blockId, required this.saver, required this.remove, }) — The dialog for the block [blockId] of [scene].
- final FilmProject project — The film the block is in, as the page had it when the menu was opened.
- final Entity scene — The scene’s version the block is in: the page’s.
- final String blockId — The block’s id, by which it is read again once every draft is written.
- final DraftSaver saver — The source’s draft, whose block moves and which is settled before Moved: the page’s own, which must still be the draft open on the scene’s file when the move writes and when it removes.
- final void Function(void Function(Map<String, dynamic> draft) apply) remove — A structural change of the source’s blocks, through its draft.

`lib/src/write_actions.dart`

class WriteRefusal — Why a write was not done, in the user’s language, and whether a re-read would let it through.
- const WriteRefusal(this.message, {this.stale = false})
- final String message
- final bool stale
typedef typedef Asked — The film a dialog is asked for in, read through the app’s container, which outlives the page.
class WriteActions — The writes the entity page offers, with their failure messages in one place.
- const WriteActions(this.ref, this.project, this.entity, this.viewer)
- final WidgetRef ref
- final FilmProject project
- final Entity entity
- final Author? viewer
- static Asked ask(BuildContext context) — The film open now, bound before a dialog’s opening waits for the drafts (stillOpen).
- static bool stillOpen(Asked asked) — Whether the film [asked] names is still the film open (ProjectController.isCurrent).
- Entity get current — The entity as the film knows it now, a write of the app’s own that landed and is not yet published included.
- Future<void> fork(BuildContext context, {Entity? of}) — Forks the page’s version — or [of], another version the page shows (Compare’s left column) — and opens the fork.
- Future<WriteRefusal?> declareEpoch(BuildContext context, String label, {int? year}) — Declares an epoch labelled [label] on the project version the page shows, for the Add epoch dialog (§8.2).
- Future<VersionStem?> createAtEpoch(BuildContext context, EntityGroup group, String epoch, { required String sourceEpoch, required Entity source, re… — Makes the viewer’s first version of [group] at the missing [epoch], and says so (§8.2).
- Future<WriteRefusal?> createOutfit(BuildContext context, String character, String epoch, String name) — Makes the viewer’s outfit named [name] for [character] at [epoch], for the New outfit dialog.
- Future<void> setOfficial(BuildContext context, bool official) — The star.
- Future<void> setPick(BuildContext context) — Makes this page’s version, as the project holds it now, the viewer’s pick (§13.4).
- Future<void> abandonPickOf(BuildContext context, Entity target) — The banner’s two answers, which name the picked version — not always the one on screen — and each say so only when they wrote something, a refusal being a message of its own.
- Future<void> keepPickOf(BuildContext context, Entity target) — Keeps the viewer’s stale pick of [target] in use and re-dates it, which clears its stale warning (§13.2).
- Future<void> setLabel(BuildContext context, String? label) — Writes [label] as the version label of this page’s file as the project holds it now, an empty one removing it.
- Future<({VersionStem? stem, WriteRefusal? refusal})> tryFork(BuildContext context) — Forks without navigating, and without turning a refusal into a snackbar.
- Future<({VersionStem? stem, WriteRefusal? refusal})> tryForkWith(BuildContext context, Entity source, Map<String, dynamic> json, { required String… — Forks [source] as the viewer’s next version holding [json], written once, in the film [film] and against [source]’s file as it was read (ProjectController.fork).
- Future<WriteRefusal?> trySaveOver(BuildContext context, Entity source, Map<String, dynamic> json, { required String film, }) — Writes [json] into [source], the viewer’s own version, against its file as it was read and in the film [film], never a later read of it: a change made to what [source] held is refused where the file changed since.
- Future<WriteRefusal?> trySave(BuildContext context, Entity base, Map<String, dynamic> json) — Saves [json], a whole document the person built from [base], as the entity’s new content, against [base]’s text: a write that landed since — the app’s own included — refuses it as stale, never put back (§7.5).
- Future<void> visit() — Records that the viewer has the entity’s media on screen (§13.4), through the state’s one door; it shows nothing, since a visit is bookkeeping and a refusal is only logged.
- Future<void> deleteTake(BuildContext context, String reference) — Deletes the file of the take [reference] names, once the entry’s deleted has reached the file (§9.0).
- Future<void> reload() — Re-reads the project (after a refused write, so the next attempt sees the current file).
- Future<T?> run<T>(BuildContext context, Future<T> Function() write, {String op = 'run', Map<String, Object?> values = const {}, Stopwatch? watch}) — Runs one write, named [op] in the log with the [values] it works on, and turns its refusals into messages.

Internal

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

lib/src/analysis_line.dart: AnalysisLine
lib/src/analysis_proposal.dart: analysisBindingKeys, AnalysisRefusal, AnalysisProposal, creditChangedPrompts, proposeAnalysis, revalidateProposal, _bindingsIn, _changedLeaves, _bindingIn
lib/src/analysis_review_dialog.dart: showAnalysisReview, _AnalysisReview, _AnalysisReviewState
lib/src/analyze_action.dart: AnalysisTarget, analysisPlacesOf, AnalysisCardBinding, AnalysisLineState, AnalysisRegistrations, _Registration, _candidates, _describes, _takes, _linkOf, _chain, AnalyzeEntryAction, +2
lib/src/import_review_text.dart: importReviewText, importReviewPair, _indent, _lines, _entry, _fenceOpen, _fenceClose, _text, _json, _heading, _bullet, _separator, +3
lib/src/other_section.dart: otherOpenProvider, OtherOpen, foldedOpenProvider, FoldedOpen, FoldedSection, OtherSection
lib/src/scene_choice_fields.dart: sceneLocationField, _locationSetter, _setLocation, sceneEpochField, _ChoiceBox, _clearButton, _SaidOutcome, _SceneLocation, _SceneLocationState, _SceneEpoch, _SceneEpochState, SceneCast, +1
lib/src/stage_control.dart: StageControl
lib/src/style_card.dart: styleBoxes, advancedTreatmentId, _chooserOpen, _proseCombo, _half, _labelled, _long, _feminine, _palette, _TreatmentFields, visualStyleSections, stylePresetField, +9
lib/src/voice_panel.dart: _edge, _Kept, _Offer, _offersOf, _KeepAnswer, _logWording, VoicePanel, _VoicePanelState, _KeepVoiceDialog, _KeepVoiceDialogState