filmopen_prompt_ui

A snapshot

This specification is a copy of docs/software/packages/filmopen_prompt_ui.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 Prompt card (Software Specification §9.3): one prompt of a document (Project Specification §9.0) as a card of its own, on every editor that holds a prompt. It sits below its three consumers, filmopen_forms, filmopen_render_ui and filmopen_browser, and imports none; it imports filmopen_insertion and filmopen_insertion_ui for the box below.

Flutter. 5 files, 1,077 lines under lib/; 56 tests in 4 files. Barrel: lib/filmopen_prompt_ui.dart.

Depends on

• filmopen_format — uses Author, Entity, EntityGroup, EntityType, FilmProject, MediaKind, MediaLocation, MediaSlot, MediaStage, PathValue, PromptPath, PromptState, ReferenceKind, ReferenceTarget, entityPlacePrompts, isGroupDeleted, mediaContainerKey, parseInstant, projectKeyOf, promptAt, promptCreatedKey, promptPluginKey, promptStateOf, promptWriterKey, promptsKey, renderStageOf, sameJson, setPathText, setPathValue, stringField and 2 more
• filmopen_store — uses AppLog
• filmopen_state — uses DraftRefusal, EditableDraft, OpenDrafts, PluginCallControl, PluginCallDone, PluginCallFailed, PluginInvocation, PromptWriter, WriterToken
• filmopen_media — uses MediaFetch, ProjectMedia, PromptToken, promptTokenCandidates
• filmopen_media_ui — uses Function, stageBorder
• filmopen_text_ui — uses MentionCandidate, MentionCandidates, mentionCandidateId, shownMentions
• filmopen_ui — uses Breakpoints, DashedBorderPainter, scopedId
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_insertion — uses BlockPlace, Function, InsertionTarget, SlotPlace, TargetPlace
• filmopen_insertion_ui — uses Function, PlaceSelection
• filmopen_test_support (dev) — uses nothing by name the digest could see

Used by

filmopen_app, filmopen_browser, filmopen_forms, filmopen_render_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/prompt_card.dart

• function String? promptAgeText(AppLocalizations l10n, String? created, DateTime now) — How long ago [created] was, as the Prompt card says it: just now under a minute, else in whole minutes, hours or days; null for a time that is not an instant (§9.0).
• function String promptTitleOf(AppLocalizations l10n, String kind) — The Prompt card’s title for a prompt of [kind] (§9.0): Reference prompt, Sheet prompt, and so on; Prompt for a kind this app does not know.
• function bool promptFieldFocused(String stem, PromptPath at) — Whether a text field of a card on the prompt at [at] of [stem] has the focus: read before a write, whose reseed may take the focus away.
• class PromptCard — One prompt of a document as a card of its own (§9.3), framing the boxes of its words.
  • const PromptCard({ super.key, required this.kind, required this.at, required this.entity, required this.read, required this.binding, required this.… — The card of the prompt at [at] in [entity], read through [read], written through [binding] where there is one.
  • final String kind — The writers’ target: character-reference, character-sheet, first-frame, … (revision 12).
  • final PromptPath at — Where the prompt stands in the document: its path, or a block’s id and its path within the block.
  • final Entity entity — The file the prompt is in: its identity is the Entity the writer is given, its author the one a prompt with no plug-in’s tag is written by.
  • final Map<String, dynamic> Function() read — The document as it stands now: the form’s draft on a page, read again at every build.
  • final EditableDraft? binding — The draft the card writes through; null where the prompt cannot be written here.
  • final List<Widget> fields — The boxes of the prompt’s words, built by the page.
  • final String? readOnlyReason — Why the prompt cannot be written here, where [binding] is null; a general sentence by default.
  • final ValueChanged<bool>? onGenerating — Told true as Generate starts and false as it ends, whether written, refused or failed.
  • final List<WriterToken> Function()? tokens — The media tokens the writer is handed (revision 13), asked of the owner once as Generate starts.
  • final String? model — The catalogue model the prompt is written for, where its caller has one chosen; none on a page.
  • final List<String>? covered — For a clip, the later blocks it covers, by id, handed to the writer with the block [at] names (revision 16).

lib/src/prompt_generate.dart

• variable final promptWritten — Told each prompt Render has written, by stem, and whether its card’s field had the focus as the write began (§9.3).
• variable const (String, String) basicPromptWriter — The stock free writer the Workflow tab’s Render asks (§9.3).
• function ({(String, String) pair, ({String id, String name, String? rate, String? quote})? llm}) startingPromptWriter(List<PromptWriter> offered) — The writer a prompt’s card starts on and the Workflow tab’s Render asks, of those [offered] (§9.3).
• typedef typedef WriterAnswer — A writer’s answer: its words, or the [code] and [reason] of having none, [failed] where it could not answer at all.
• function Future<WriterAnswer> askWriter({required String target, required Entity source, required (String, String) writer, String? model, String? blockId, L… — Asks [writer], a plug-in’s tag and a writer’s id, to write the prompt of [target] from [source] (§9.0).
• function String? writerAnswerLine(AppLocalizations l10n, WriterAnswer answer) — The sentence for an [answer] without words.
• function void withWords(Map<String, dynamic> draft, PromptPath at, String positive, String? negative, String tag, String id) — Sets a writer’s words on the prompt at [at] of [draft], in place (§9.0): positive, negative (removed where the writer gave none) and the writer’s pair, [tag] and [id], and no created, which the writer stamps; it…
• function String? promptHolderUpdated(Map<String, dynamic> document, PromptPath at) — The holder’s updated, what [promptStateOf] reads a prompt against (§9.0).
• function String? promptWriterTarget(EntityType type, String kind) — The writers’ target of the stored [kind] of a prompt on a document of [type]; null for a kind with no box.
• function TargetPlace? promptPlaceOf(EntityType type, PromptPath at) — The picture or clip place the prompt at [at] of a document of [type] is rendered into; null for any other prompt: a voice’s, whose sample renders from its audition, and a treatment’s, which renders into no place.
• function String generateKey(String placeKey, String kind) — The key of a Generate box: the place’s InsertionTarget.placeKey, then the kind of the prompt it is rendered from.
• function bool promptByWriter(Map<String, dynamic>? prompt) — Whether a writer wrote [prompt]: it carries the pair, [promptPluginKey] and [promptWriterKey] (§9.0), which a person’s words remove; a plug-in’s analysis carries the plug-in alone.
• function bool generateReads(bool? override, PromptState state, {required bool byWriter}) — What a Generate box reads for a prompt in [state]: the person’s [override] where there is one, else checked while the prompt is empty, or outdated with words a writer wrote ([byWriter]), never over the person’s own…

lib/src/prompt_mentions.dart

• class ProjectMentionCandidates — The project’s contextual names and resolved pictures for the shared mention chooser.
  • ProjectMentionCandidates(this._project, this._viewer, {this.prompt}) — Binds candidates to the rendered project and its current viewer; [prompt] names the prompt kind whose source holds it, for the log.
  • final String? prompt — The prompt kind of the [PromptMentionCandidates] this serves, or null for a prose box’s own source.
  • FilmProject get project — The project the candidates are read from.
  • Author? get viewer — The viewer each entity resolves for.
  • bool update(FilmProject project, Author? viewer) — Updates contextual membership without replacing the controller’s candidate source.
• class PromptMentionCandidates — A prompt box’s @ source (§9.8): the media a prompt of the writers’ [kind] may name, and nothing else offered.
  • PromptMentionCandidates(this.kind) — A source for prompts of [kind] (character-sheet, first-frame…), empty until [update].
  • final String kind — The writers’ prompt kind the tokens are for.
  • bool update(FilmProject project, Author? viewer, Entity document, AppLocalizations l10n) — Binds to the project, viewer, the file the prompt is on and the names’ language; true at the first binding and where the list a box has read changed.
• function String promptTokenName(AppLocalizations l10n, PromptToken token) — What a prompt’s chooser and chip call [token].

lib/src/prompt_words.dart

• typedef typedef ClearedWriter — The writer a person’s words took away from a prompt: the plug-in’s tag and the writer’s id, as the prompt held them.
• function ClearedWriter? withPromptWordChanged(Map<String, dynamic> document, PromptPath at, String side, String text) — Writes a person’s words into one side of a prompt, taking its writer away where they changed (§9.0).