filmopen_state

A snapshot

This specification is a copy of docs/software/packages/filmopen_state.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 application’s state, in Riverpod: settings (settingsProvider, the username — default where none is chosen, changed through setViewerHandle, which writes the open drafts first —, development mode, and settingsTabProvider, Settings’ open tab), the open project (projectProvider: openSample / openDirectory / createProject, refresh, saveEntity, fork, setOfficial, setPick, createOutfit (a named outfit, its id the writer’s; an id taken from outside meanwhile is the refusal, nothing tried again), and addChild / removeChild / moveChild, which add a folder or a scene to a children list, take an entry out of one and move one — within a list, between two (the destination first, the origin second) or out of Not in the script —: the entity first and the parent second, everything that can be known refused before anything is written, each file written as it was checked (a change made meanwhile is refused as stale, never absorbed), and the parent’s change routed through the draft a form has open on that file), navigation (browserProvider.navigate, Selection — ScriptSelection for the Script page among them —, the tree model and TreeBuilder, scriptOutlineProvider, the one walk of the script that the tree and the pages read — workingScriptOutline, its lists the viewer’s assistant draft’s where one exists, so that what the assistant files and what a person adds there are seen at once —, and ScriptRowText, what a row of it says wherever it is drawn), launch arguments, localisation, the bundled model catalogue read once (catalogueProvider, the format’s one reader, which Provider keys, dictation and the plug-in host share), PageAccess (what a page may do with the file on screen, canRunPlugins and childrenLock among it), WriteProblemText (the sentence for a refused write, here so that the tree and the forms both say it), and the constants the packages read.

Flutter. 81 files, 22,989 lines under lib/; 1251 tests in 106 files. Barrel: lib/filmopen_state.dart.

Depends on

• filmopen_format — uses AllocatedId, Author, BatchStem, BlockMerge, BlockMergeProblem, Catalogue, ChildEntry, ChildProblem, Entity, EntityCategory, EntityGroup, EntityType, EntityVersions, EpochDeclaration, FileNameParser, FilmProject, MediaEntry, MemoryProjectSource, Money, Pick, PickReason, PlatformFile, ProblemKind, ProjectArea, ProjectSource, Resolution, SceneCard, ScriptBlock, ScriptOutline, ScriptRow and 64 more
• filmopen_store — uses AppLog, ContentProblem, DiscardOfficialException, EntityExistsException, EpochDeclaredPickFailedException, EpochSourceUnavailableException, ForkSourceUnreadableException, GuardRule, Guards, HeldLibrary, IdentityChangedException, InvalidContentException, NextEpochLoweredException, NoSelectedProjectException, NoViewerException, NotDirectorException, NotYourFileException, NotYourTakeException, OutfitParentUnavailableException, ProjectLoader, ProjectReadOnlyException, ProjectWriter, RecordedWrite, TakeStillNamedException, WriteRecord, canCreateProjects, copyImportedProjectTo, copyProjectTo, createProject, firstSceneKeys and 7 more
• filmopen_fdx — uses ScriptImportException, importScriptFile
• filmopen_media — uses LocalMediaStore, MediaFetch, MediaFetchProblem, MediaFetchState, MediaFetchStatus, MediaStore
• filmopen_insertion — uses AudioProbe, Function, InsertionBinding, InsertionEnvironment, InsertionPatchResult, InsertionService, InsertionTarget, producerJobKind
• filmopen_jobs — uses JobAction, JobActionAck, JobEngine, JobPhase, JobUnavailable, JobView, Producer, describeJobError
• filmopen_sync — uses ReconcileIncomplete, SyncArrival, SyncAvailability, SyncBinding, SyncEnvironment, SyncLane, SyncLedger, SyncParts, SyncRules, SyncService, SyncStatus, SyncTarget
• filmopen_platform — uses AssetProjectSource, BackgroundTransfers, FolderWatch, HostEvent, HostOutcome, HostReport, HostStatus, IncomingLinks, SampleFolderSource, documentsDirectory, folderDialogsAvailable, hasAppFiles, libraryDirectory, preferencesFilePath, projectsDirectory, projectsInAppFolder, readBundledText, watchFolder
• filmopen_l10n — uses PluginCallOutcomeWords, appStringsByKey
• filmopen_exchange — uses ArgSpec, ExchangeId, ExchangeKind, ExportDocument, FieldPath, ImportAction, ImportChange, ImportPlan, ImportProblem, ImportResult, ImportStage, ImportWriter, StageOutcome, all, applyPlan, artifactMatches, exportEntityDocument, exportScope, focus, planImport, scopeRegistry, scopes
• filmopen_engine — uses EngineException, FakeEngine, LoggingEngine, MediaProbe, TimelineEngine
• filmopen_timeline — uses MediaProber, SceneTimeline
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: flutter_riverpod, shared_preferences, crypto.

Used by

filmopen_account, filmopen_app, filmopen_assistant_ui, filmopen_automation, filmopen_browser, filmopen_compare, filmopen_device, filmopen_dictation, filmopen_forms, filmopen_insertion_ui, filmopen_jobs_ui, filmopen_keys, filmopen_picker, filmopen_plugin_dev, filmopen_plugin_host, filmopen_plugins_ui, filmopen_prompt_ui, filmopen_recorder, filmopen_relay, filmopen_render_ui, filmopen_sharing, filmopen_support, filmopen_timeline_ui, filmopen_tree

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

• class AccountAccess — The account’s access token, as a sync target that sends to filmopen.ai asks for it inside an operation.
  • const AccountAccess() — Creates an access without account or transport work.
  • static AccountAccess get current — The installed access; [NoAccountAccess] by default.
  • static void install(AccountAccess access) — Installs [access] without calling it.
  • Future<String?> accessToken() — The session’s access token, refreshed where it is past its hour; null without a session.
• class NoAccountAccess — The access of a build that installed none: no token, no connection.
  • const NoAccountAccess() — The inert access.

lib/src/account_ledger.dart

• class LedgerRow — One movement of the account’s ledger, as the website records it.
  • const LedgerRow({required this.id, required this.at, required this.kind, required this.cents, this.job}) — A movement of [cents] of kind [kind] at [at], of the lending job [job] where the record names one.
  • final String id — The record’s id.
  • final DateTime at — When the money moved, in UTC.
  • final String kind — The ledger’s kind as the website spells it: settlement, earning, or any other.
  • final int cents — What moved, in US cents, signed: a credit positive, a debit negative.
  • final String? job — The lending job’s id where the record names one; null on every other movement, a funded call’s among them.
• class LedgerReading — What a read of the ledger answers.
  • const LedgerReading()
• class LedgerRead — The records read, the months the account has any record in, and whether every record was read.
  • const LedgerRead({required this.rows, required this.months, required this.complete}) — [rows] newest first, [months] as the website lists them, [complete] false where older pages were left unread.
  • final List<LedgerRow> rows — The movements read, newest first.
  • final List<String> months — Every month the account has a record in (2026-10), whatever month was asked for.
  • final bool complete — Whether every record was read; false where the read stopped before the ledger’s end.
• class LedgerSignedOut — Nobody is signed in, or the session was refused: nothing to read.
  • const LedgerSignedOut() — The signed-out reading.
• class LedgerUnreadable — The ledger could not be read, for the reason [code] names.
  • const LedgerUnreadable(this.code) — An unreadable ledger, by its code.
  • final String code — Why: the website’s refusal code, malformed or unreachable.
• class AccountLedger — The host-installed reader of the account’s ledger, inert until installed.
  • const AccountLedger() — Creates a reader without account, credential or transport work.
  • static AccountLedger get current — The installed reader, signed out by default.
  • static void install(AccountLedger ledger) — Installs a reader without reading or starting anything.
  • Future<LedgerReading> read(String? month) — Reads [month]’s records (2026-10), or every month’s when null; never throws.
• class NoAccountLedger — The default reader, which is signed out and sends nothing.
  • const NoAccountLedger() — Creates the inert reader.

lib/src/account_names.dart

• enum AccountNamesStatus — Where the account’s names stand: nobody signed in, being read, read, or not readable.
  • values: signedOut, reading, read, failed
• class AccountNames — The account’s names as last read for the account signed in now, the primary first.
  • const AccountNames.signedOut() — Nobody is signed in: nothing is read.
  • final AccountNamesStatus status — The status of the read.
  • final String? accountId — The account the names are for; null signed out.
  • final List<AccountIdentity> names — The names, the primary first; empty unless [status] is [AccountNamesStatus.read].
  • final String? code — Why the names could not be read, a refusal’s code or failed, where [status] is [AccountNamesStatus.failed].
  • bool has(String username) — Whether [username] is one of the names.
• variable final accountNamesProvider — The signed-in account’s usernames, read once per account, which set the username at sign-in (§6.6).
• class AccountNamesController — The controller of [accountNamesProvider].
  • Future<void> refresh({required String reason}) — Reads the names again for the account signed in now — Retry after a failure, or after a claim — keeping what was read on screen until the answer.
  • Future<ViewerChange> choose(String username, {required String source, String reason = 'chosen'}) — Makes [username] the username through the one transition (setViewerHandle, the open drafts written first), logged by [source] — signIn, settings, popup, director — with the name and what it came to, a refusa…

lib/src/account_opener.dart

• variable final accountOpenerProvider — The one way the app asks a person to sign in to filmopen.ai (§9.4): [AccountOpener.open] lands on Settings and asks the rail’s profile to open the account’s popup, where the sign-in is.
• class AccountOpener — Asks for the account’s popup, on Settings ([accountOpenerProvider]).
  • void open({String? reason}) — Shows Settings and asks the rail’s profile to open the account’s popup; [reason], where given, is said at the popup’s top: why the person is asked to sign in.
  • String? takeReason() — The reason the last request gave, once: the popup that request opens says it, and no later one.

lib/src/account_projects.dart

• class AccountIdentity — One of the account’s community names: its id, the name, and whether it is the account’s primary.
  • const AccountIdentity({required this.id, required this.username, required this.isPrimary}) — An identity as the website answered it.
  • final String id — The website’s uuid of the identity.
  • final String username — The name, as the website keeps it.
  • final bool isPrimary — True for the account’s one primary name; false for an alias.
• class ProjectRecord — A project recorded under the account: where it lives, under which name, by the id this device made for it.
  • const ProjectRecord({ required this.id, required this.username, required this.tag, required this.name, required this.provider, required this.locati… — A record of the project [tag] named [name], directed as [username], kept by [provider] at [location].
  • final String id — The record’s uuid, made by the app before the create and kept with the folder (Settings.recordOf).
  • final String username — The username or alias the project is recorded under.
  • final String tag — The project’s tag.
  • final String name — The project’s name.
  • final String provider — Where it lives: local, filmopen, drive, or a word this build does not know, which is kept as it came.
  • final String location — The place within [provider]: a folder path, a cloud id.
  • Map<String, Object?> toJson() — The record as the website’s routes carry it.
• typedef typedef ProjectRecordResult — A create’s answer: the record, and whether the website had it already under the same id (a replay).
• class AccountProjectsRefused — A refusal of the account’s projects, by its code alone — with the website’s status where one answered.
  • const AccountProjectsRefused(this.code, {this.status}) — A refusal under [code].
  • final String code — The refusal’s code, for the consumer to word; never a server’s words.
  • final int? status — The HTTP status that carried the refusal, null where nothing was sent or nothing answered.
• class AccountProjects — The account’s usernames and project records (§6.6): each call answers its value or throws [AccountProjectsRefused].
  • const AccountProjects() — Creates a client without account or transport work.
  • static AccountProjects get current — The installed client; [NoAccountProjects] by default.
  • static void install(AccountProjects client) — Installs [client] without calling it.
  • Future<List<AccountIdentity>> identities() — The account’s names, the primary first (GET /v1/community/self).
  • Future<PublicName?> name(String username) — The name [username] as anybody may read it (GET /v1/community/names/{username}, sent with no bearer), or null where nobody holds it: the one client of the community’s public names.
  • Future<AccountIdentity> claim(String username, {required bool primary}) — Claims [username] for the account, as its primary where [primary], else as an alias (POST /v1/community/identities).
  • Future<ProjectRecordResult> createRecord(ProjectRecord record) — Records [record] under its own id (POST /v1/projects); the same id sent again answers replayed: true.
  • Future<List<ProjectRecord>> records() — The account’s project records (GET /v1/projects).
  • Future<ProjectRecord> updateRecord(String id, {required String provider, required String location}) — Moves the record [id] to [location] at [provider] (PUT /v1/projects/{id}).
• class NoAccountProjects — The client of a build that installed none: every call is refused account-projects-unavailable; nothing is sent.
  • const NoAccountProjects() — The inert client.

lib/src/account_snapshot.dart

• enum AccountAuthentication — Authentication reported by the account service, independent of the local author.
  • values: authenticated, signedOut, loading, unavailable
• class AccountBalance — A known, unknown or unavailable available balance, never a fabricated zero.
  • const AccountBalance() — Creates a balance state without consulting an account or ledger.
  • Map<String, Object?> toJson() — The public allowlisted balance data, without ledger entries or identifiers.
• class KnownAccountBalance — An observed available amount in integer minor units with an ISO 4217 code.
  • KnownAccountBalance({required this.minorUnits, required this.currency, required DateTime observedAt, this.balanceMinorUnits}) — Keeps the observation in UTC and refuses a malformed three-letter currency code.
  • final int minorUnits — The available amount, in the currency’s minor units rather than a floating point value.
  • final int? balanceMinorUnits — The account’s whole balance, held amounts included, in the same minor units; null where it is not known.
  • final String currency — The ISO 4217 currency code supplied by the account implementation.
  • final DateTime observedAt — When the account implementation observed this amount.
• class UnknownAccountBalance — A balance whose amount is not known, with no implied available amount.
  • const UnknownAccountBalance() — Creates the unknown state without supplying an amount.
• class UnavailableAccountBalance — A balance that the installed account service cannot supply.
  • const UnavailableAccountBalance() — Creates the unavailable state without supplying an amount.
• class AccountSnapshot — The read-only public account snapshot, with no identity, token, e-mail or ledger fields.
  • AccountSnapshot({required this.authentication, this.balance = const UnknownAccountBalance(), this.accountId}) — Allows a known balance only with authenticated state.
  • final AccountAuthentication authentication — The service’s authentication state, never a preference hint or local author.
  • final AccountBalance balance — The available balance’s explicit knowledge state.
  • final String? accountId — The signed-in account’s user id, which binds what is read for the account to it (§6.6); never serialized or printed.
  • Map<String, Object?> toJson() — Serializes only the public allowlist, with absent amounts remaining absent.
• class AccountSnapshots — The host-installed source of public account snapshots, inert until installed.
  • const AccountSnapshots() — Creates an account source without initializing any account SDK.
  • static AccountSnapshots get current — The installed source, unavailable by default.
  • static void install(AccountSnapshots source) — Installs a source without reading it or starting a listener.
  • static Stream<void> get installations — Replacement notifications for consumers already observing the source.
  • AccountSnapshot get snapshot — The latest public snapshot, read without starting account work.
  • Stream<void> get changes — Signals after the snapshot changes; implementations publish the value first.
• class NoAccountSnapshots — The default account source, which authenticates nobody and starts nothing.
  • const NoAccountSnapshots() — Creates the inert account source.

lib/src/app_paths_provider.dart

• variable final preferencesLocationProvider — The preferences file on this machine, for Settings to show.
• variable final projectsInAppFolderProvider — Whether projects live in the app’s own folder — a phone — rather than in a folder the person names.
• variable final folderDialogsAvailableProvider — Whether the operating system offers a folder dialog: Open project…’s picker, Copy to a folder…, the library’s folder and the media folder’s Browse are offered only where it does.
• variable final projectsDirectoryProvider — Where a new project is made on a platform whose projects live in the app’s own folder: the folder, created.
• variable final documentsDirectoryProvider — The person’s documents folder (documentsDirectory), where New project proposes a project on a computer when it knows no better place (§9.2).
• function String? parentFolderOf(String path) — The folder [path] is in, or null where [path] names none: what New project reads off the last project opened.
• variable final newProjectParentProvider — Where New project proposes to make a project on a computer (§9.2), looked up afresh each time the dialog opens.

lib/src/app_version_provider.dart

• variable final appVersionProvider — The application’s version, supplied by main from the application’s own consts.dart, which keeps it equal to pubspec.yaml (CLAUDE.md §5).

lib/src/assistant.dart

• variable const assistantTextProtocol — The identity a text provider declares as x.assistantText.protocol beside its verified output parameter (§6.11a).
• variable const assistantCloseLimit — How long a close the person asked for waits, at most, for the session’s work in flight (§7.4).
• variable const assistantCloseRecordSlice — What a close keeps of its deadline for the record’s last write (§7.4).
• variable const assistantQuitLimit — How long the app’s quit lets a session’s work in flight settle before its record is closed, inside the exit’s 10 s (§7.4).
• class AssistantTarget — A field identity supplied by a form and independently validated by the host: an entity and a field (§6.11a).
  • factory AssistantTarget.of(String stem, String field) — Identifies one semantic field, named by the source version’s [stem] and the [field], without granting permission to read or write it; an unreadable stem names no entity.
  • final ExchangeId? id — The entity’s exchange id, without author or version; null where the stem names no entity.
  • final String field — The field’s JSON path in the entity.
  • final String stem — The source version’s stem.
  • String get fieldId — The existing global field identifier, derived so the button’s door keeps its field: identifier.
  • String get entityType — The format’s entity type token.
  • String get jsonPath — The actual JSON leaf path.
• class AssistantDraft — A click-time draft snapshot and a guard against applying to a later generation.
  • AssistantDraft({required Map<String, Object?> document, required this.generation, required this.isCurrent}) — Takes a private copy of the draft supplied on the user’s gesture.
  • final Map<String, Object?> document — The unsaved document, never collected during widget build.
  • final int generation — The form’s draft generation at the gesture.
  • final bool Function() isCurrent — Whether the same editable form and draft generation still exist.
• class FrozenAssistantDraft — A View form’s source: the entity as read, current while its file’s text is the text read (§6.11a).
  • FrozenAssistantDraft({required super.document, required this.rawText, required String? Function() rawTextNow}) — Freezes [document] and [rawText] on the gesture; [rawTextNow] reads the file’s text as the project has it now.
  • final String? rawText — The file’s text as read, without which no frozen source is current.
• enum AssistantApplyKind — Where Apply starts from, decided from the pick and the viewer, never from the version on screen (§6.11a).
  • values: update, fork
• class AssistantApply — What Apply will do with the assistant’s proposal, as codes and stems: the words are the dialog’s.
  • const AssistantApply(this.kind, { required this.stem, required this.author, required this.v, this.onScreen, this.onScreenAuthor, this.onScreenV, }) — Names the version in use and, where it differs, the version on screen.
  • final AssistantApplyKind kind — Update or fork.
  • final String stem — The version in use, which the proposal changes.
  • final String author — The version in use’s author.
  • final int v — The version in use’s number.
  • final String? onScreen — The version on screen where it is not the version in use; null where it is.
  • final String? onScreenAuthor — The version on screen’s author, where it is not the version in use.
  • final int? onScreenV — The version on screen’s number, where it is not the version in use.
  • bool get lookingAtOther — Whether the person looks at another version than the one the proposal changes.
• class AssistantModelSelection — A catalogue model preference, with route details only for a resolved call.
  • const AssistantModelSelection({required this.model, this.platform = '', this.provider = ''}) — Names a model; only the host’s resolved calls carry a platform and provider.
  • final String model — The catalogue model identifier.
  • final String platform — The catalogue access platform.
  • final String provider — The stable text provider tag.
  • String encode() — The one machine preference’s serialized value.
  • static AssistantModelSelection? decode(String? text) — Reads a model id, or the model alone from a legacy saved route.
• class AssistantChoice — A declaratively discovered assistant, including unavailable choices and their reason.
  • const AssistantChoice({ required this.tag, required this.name, this.reason, this.declaresCatalog = false, this.catalog, this.portrait, }) — Describes a package without executing any JavaScript.
  • final String tag — The stable package tag.
  • final String name — The localized display name.
  • final String? reason — A safe refusal code, or null for a runnable package.
  • final bool declaresCatalog — Whether the manifest names a catalog (x.assistant), read from its metadata whether the catalog loaded or not.
  • final AssistantCatalog? catalog — The catalog, null until it is loaded or where it was refused.
  • final Uint8List? portrait — The portrait’s bytes, null until they are loaded or where they were refused.
• class AssistantOffer — One action offered where the person is, with its readiness: one chip each (§6.11a).
  • const AssistantOffer({required this.action, required this.level, this.label, this.reason, this.model, this.provider, this.funding, this.route = con… — Offers [action] in its [level]’s group, enabled where [reason] is null.
  • final AssistantAction action — The catalog’s action.
  • final AssistantLevel level — The group it is offered in; the dock names the group from the level and where the person is.
  • final String? label — The action’s resolved label.
  • final String? reason — Null where the action may run; else noProject, needsEntity, catalog, loading, untrusted, disabled or incompatible; noModel where there is no candidate model at all; else the first candidate’s refusal —…
  • final String? model — The first model refused, for the tooltip.
  • final String? provider — The provider tag the first refusal named, where it named one: for credentials, the one whose key is missing.
  • final String? funding — How an action that may run is funded: key for the person’s own key, credit for FilmOpen credit (§6.11a); null where it may not run.
  • final Map<String, Object?> route — The exact decided completion route, including a refused saved choice where one is unavailable.
• class AssistantModelChoice — A catalogue text model shown in Settings, including its unavailable reason.
  • const AssistantModelChoice({required this.selection, required this.name, this.reason}) — Describes one exact route without checking keys or contacting a provider.
  • final AssistantModelSelection selection — The route saved by a deliberate user selection.
  • final String name — The displayed catalogue model name.
  • final String? reason — A safe refusal code, or null for a route supported by this host.
• class AssistantPreferences — The machine’s assistant selection and its single text-model preference.
  • const AssistantPreferences({this.assistantTag = 'fo-assistant', this.model, this.error}) — Defaults to fo-assistant only when there is no explicit saved assistant choice.
  • final String assistantTag — The selected assistant’s stable tag.
  • final AssistantModelSelection? model — The explicit model route; null requires selection or one-time adoption.
  • final String? error — A preference write failure code, never storage error text.
• variable final assistantPreferencesProvider — Assistant preferences share the app’s existing preference store and contain no transcript or secret.
• class AssistantPreferencesController — Persists only assistant and model identities, after deliberate selection or host adoption.
  • static const assistantKey — The selected assistant preference key.
  • static const modelKey — The single Settings text-model preference key.
  • Future<void> selectAssistant(String tag) — Saves a stable tag; changing it affects only future sessions.
  • Future<void> selectModel(AssistantModelSelection selection) — Saves the model id for future calls, without changing dictation’s speech service.
  • Future<void> clearModel() — Removes the model override so the assistant decides, using the same write order as selections.
• class AssistantMessage — A plain-text message held only for the lifetime of the dialog.
  • const AssistantMessage(this.role, this.content, {this.display}) — Holds one user or assistant turn in its original order.
  • final String role — Either user or assistant, never instructions supplied by the user as system text.
  • final String content — The message’s plain text, never diagnostic data: what the model is told.
  • final String? display — What the person saw where it differs from [content] — a streamed turn’s every call, or a stopped turn’s words; shown, never sent.
  • Map<String, Object?> toJson() — The serialized message supplied to the plugin.
• class AssistantReply — The finite result of one field-assistant invocation.
  • const AssistantReply(this.state, { this.reply, this.code, this.finalizationRequired = false, this.admitted = true, this.proposalId, this.display, t… — Carries a typed state and optional prose, with no executable project patch.
  • final String state — awaitingUser, completed, unsupported or error.
  • final String? reply — Plain-text discussion or draft: the last model call’s text, what the model is told later and what Apply may finalize.
  • final String? display — What the person saw of a streamed turn — every call’s words, the last call’s replaced by [reply] — where it differs from [reply]; null where it equals it (§6.11a).
  • final String? code — A safe refusal code, kept separate from provider prose.
  • final String? says — The provider’s own words for a failed call — its plug-in’s message, a refusal’s explanation — shown beside [code]’s sentence (§6.11a); null where it said none.
  • final bool finalizationRequired — Whether the retained draft still needs a future validated finalizer.
  • final bool admitted — Whether the host admitted this operation, defaulting to true when billing remains uncertain.
  • final String? proposalId — The proposal a revision-6 finalizer’s import queued under the operation, for the dialog to review (§6.11a).
  • final List<Map<String, Object?>> exchange — The turn’s tool exchange in the host’s wire shape — each tool_calls message and each tool answer, in order, as far as answered — whatever its outcome: what the chat’s record keeps (§7.4); empty where no tool ran.
  • AssistantReply withExchange(List<Map<String, Object?>> exchange) — This reply carrying [exchange].
• class ChangeNotice — What a chat tells the person of a model’s change its record refused (§6.11a): the paths not applied, on [target], and whether a later write corrected it.
  • const ChangeNotice(this.target, this.paths, {this.corrected = false}) — The notice of [paths] refused on [target]; [corrected] once a later write of it covers them.
  • final String target — The entity the refused write named: an update’s id, or a creation’s type and name.
  • final List<String> paths — The refused paths inside the content, as the refusal names them without content..
  • final bool corrected — Whether a later successful write to [target] covered every path.
• function ChangeNotice? noticeAfter(ChangeNotice? before, List<Map<String, Object?>> exchange) — [before] as the tool answers of [exchange] leave it, in their order (§6.11a): a write refused with its record’s problems (shapes) is a new notice; it is corrected only by a later successful call of the same write…
• class AssistantSessionBackend — One bound backend, owned by a host or scripted fixture and never by a widget.
  • Listenable get changes — Reports changes that can invalidate the frozen binding.
  • String? get staleReason — Null while the original target, model, package and credential generations still hold.
  • Future<AssistantReply> send(Map<String, Object?> request, PluginCallControl control) — Runs one invocation until it answers, the person stops it or something fails, preserving host cancellation and Usage; no count, size or clock of the app’s own ends it (§6.11a).
  • String? get proposalId — The operation’s proposal while it waits for the person; null once applied or discarded, or where none was made.
  • Future<void>? get inFlight — The tool call under way, which a close lets settle before the session’s record is closed (§7.4); null where none.
  • Map<String, Object?>? get fundingRoute — The funding route the session was admitted on and every turn of it uses, as the host decided it at the opening; null where the backend holds none.
  • void close() — Releases only this session’s listeners and work.
• class AssistantService — The app’s injectable assistant service; construction and discovery perform no model calls.
  • static AssistantService current — The installed host service, unavailable until root composition supplies one.
  • Listenable get changes — Signals declarative inventory or readiness changes.
  • List<AssistantChoice> get assistants — Installed packages with their declarative field support.
  • List<AssistantModelChoice> get models — Text models offered by enabled providers, once per model with its unavailable reason.
  • List<AssistantOffer> offers(String tag, AssistantWhere where) — The actions [tag]’s catalog offers at [where], with their readiness; none from a service without a catalog road.
  • Future<AssistantSession> openAction(AssistantRequest request, AssistantPreferences preferences) — Opens the chat a catalog action asks for, on the person’s gesture; refused where the service has no such road.
  • void note(String event, Map<String, Object?> data) — Writes one line of the assistant’s log for a caller with no log of its own, the UI: the event and its data; inert unless the installed service writes it.
• class UnavailableAssistantService — The inert service used by tests and builds that have no accepted or experimental host adapter.
• class AssistantUnavailable — A safe refusal surfaced by the field dialog before any provider request.
  • const AssistantUnavailable(this.code, {this.plugin, this.route = const {}}) — Carries a localizable code and the refused provider and route where known.
  • final String code — The refusal code.
  • final String? plugin — The provider whose chosen route was refused, where the refusal names one.
  • final Map<String, Object?> route — The refused route carried whole from the host’s decision.
• enum ConversationPhase — The typed phases of a text conversation.
  • values: start, turn, finish
• class ConversationTurn — An immutable text turn carrying the session’s frozen target and context.
  • ConversationTurn({ required this.sessionId, required this.phase, required this.target, required this.model, required this.viewer, required this.dra… — Copies the context and history so a backend cannot mutate a later turn.
  • final String sessionId — The host-issued session identity.
  • final ConversationPhase phase — Start, user turn or local finish.
  • final AssistantTarget? target — The original semantic field and global identifier; null for a catalog action with no field.
  • final AssistantModelSelection model — The exact text model and provider chosen for this session.
  • final String? viewer — The viewer captured when the host bound the session; null where the action reads no project.
  • final int? draftGeneration — The original editable draft generation; null where the action reads no draft.
  • Map<String, Object?> get context — A private copy of the allowlisted initial context, never a live project read.
  • final List<AssistantMessage> messages — The preceding user and assistant messages in their original order.
  • final String? input — The current user message, present only for a user turn.
  • final int turn — The counted model turn, unchanged by Finish.
  • Map<String, Object?> toJson() — Serializes the existing plugin envelope without granting additional host authority.
• class AssistantSession — One memory-only conversation with a frozen model, and the field or request it opened for.
  • AssistantSession({ required this.id, required this.target, required this.model, required this.backend, required Map<String, Object?> context, requi… — Captures immutable JSON and watches only the supplied session’s validity.
  • final String id — The host-issued opaque session identity.
  • final AssistantTarget? target — The validated original field; null for a catalog action with no field.
  • final AssistantModelSelection model — The frozen text route.
  • final AssistantSessionBackend backend — The host-owned execution binding.
  • final String? viewer — The original viewer handle, never a credential; null where the action reads no project.
  • final int? draftGeneration — The draft generation captured on opening; null where the action reads no draft.
  • final AssistantApply? apply — What Apply will do on the conversation’s road, computed by the host on opening; null for a chat, which writes through the commands, and where nothing resolves.
  • final AssistantRequest? request — The catalog action this session opened for; null where none was given.
  • final String? asks — The question the dock asks before any model call, the action’s asks where the project holds no summary (§6.11a); null where the session starts as it opens.
  • bool get canApply — Whether Apply may follow, on the conversation’s road: the action has a finalize prompt, the field a string leaf, the host an apply; never for a chat (§6.11a).
  • String? get proposalId — The finalizer’s proposal while it waits for the person (§6.11a).
  • bool busy — Whether one invocation is waiting or running.
  • String? error — The last localizable error; transcript and unsent input are kept after an error.
  • String? get says — The provider’s own words for [error], while it is the error they came with (§6.11a); null otherwise.
  • AssistantReply? result — The last completed result, including its finalization marker.
  • ChangeNotice? changeNotice — The model’s last refused change and whether it corrected it, for the person to see (§6.11a); null where none.
  • List<AssistantMessage> get messages — The transcript, immutable to callers and never persisted: [history] is what the chat’s record keeps.
  • List<Map<String, Object?>> get history — The conversation as the chat’s record keeps it (§7.4), a copy: the person’s words and the assistant’s final words with their at, and between them each turn’s tool exchange in the host’s wire shape; never a stopped t…
  • ValueListenable<String> get partial — The running turn’s growing text, as the provider pushes it (§6.11a); empty while idle.
  • ValueListenable<String> get note — The turn’s last reasoning sentence (§6.11a): replaced by the next, kept across the turn’s calls, empty when there is none and cleared when a call’s words begin, the turn ends or is stopped; never in [messages] nor tol…
  • int get call — The turn’s model call under way, numbered from 1; 0 while idle.
  • DateTime? get callStartedAt — When [call] began, by [clock]; null while idle and before the first call.
  • int get heardCall — The last call that has said something — reasoning, words or its answer returned —, 0 for none; a [call] after it has said nothing yet.
  • DateTime? get turnStartedAt — When the running turn was sent, by [clock]; null while idle.
  • static DateTime Function() clock — The clock a turn’s start and the dock’s seconds read; a test sets its own.
  • int get turns — The number of potentially billed model turns, excluding explicit host refusals before admission.
  • bool get stale — Whether the binding was invalidated; a stale session cannot be retargeted.
  • bool get completed — Whether Finish has preserved the draft.
  • Future<bool> settle(Future<void> deadline, {required Duration left}) — Lets the session’s work end before its close is recorded (§7.4): the turn cancelled, then its own send and the host’s tool call in flight awaited until [deadline] completes — which [left] it is from now; whether both…
  • void hurry() — Cancels a turn begun since the close began (§7.4): the film is being left or the app quits.
  • void notice(String code) — Shows [code] in the chat — a change the session could not record (§7.4) — until the next turn clears it.
  • Future<void> start() — Starts the greeting once, on the same user gesture that opened the dialog.
  • void ask(String question) — Shows [question] as the assistant’s first words without a model call (§6.11a): the person’s answer is the first turn, and the model reads the question before it.
  • Future<void> send(String input) — Sends nonblank user text once, retaining it in the transcript even on failure.
  • Future<void> finish() — Preserves the agreed text for later finalization without writing a project.
  • void cancel() — Stops only the current turn and keeps its potentially billed outcome uncertain.
  • Future<bool> Function(String stage)? recorder — Writes the chat’s record for [stage] — send, turn — awaited at the turn’s two edges (§7.4); whether it was written.
• class AssistantWhere — Where the person is, as the assistant reads it (§6.11a).
  • const AssistantWhere({required this.rail, this.section, this.entity, this.pending, this.record, this.projectKey, this.tab, this.field}) — Names a place; nothing but the rail is known where no project is open.
  • final String rail — The rail’s page by its name ([NavIndex.nameOf]).
  • final String? section — The page: null where no project is open, else an entity type’s prefix, or overview, script, other, batch.
  • final ExchangeId? entity — The page’s entity: the held field’s, else the selected entity’s, or the selected batch’s; null on another page.
  • final EntityType? pending — The type of the pending set whose page this is (section batch, no entity: a set is no [ExchangeId]); null on another page.
  • final EntityType? record — The type of the set record whose page this is (section batch, a comp’s or a chat’s: a set is no [ExchangeId]); null on another page.
  • final Object? projectKey — Which project is open ([projectSourceKeyProvider]), null where none is; the dock’s session.stays logs it.
  • final String? tab — The settled tab’s name, served only while the rail is project.
  • final AssistantFieldAt? field — The field held, served only while the rail is project and the field is of the version the tabs show.
• class AssistantFieldAt — A field a form publishes as the one the person is at, with its owner’s identity token (§6.11a).
  • AssistantFieldAt({ required this.owner, required this.stem, required this.type, required this.section, this.sectionLabel, required this.pairId, req… — Describes the field; [draft] is read only on the person’s gesture, and [readPaths] is copied, never shared.
  • final Object owner — The publishing wrapper’s identity: only it may take the field back.
  • final String stem, type, section, pairId, label — The version’s full stem, its entity type’s prefix, the form section’s id, the field’s pair id and its label.
  • final String? sectionLabel — The form section’s title as the form shows it, which heads a form section’s actions in the dock; null where the publisher has none.
  • final List<String> readPaths — The keys the form’s field owns: one for a plain field, several for a composite such as media; never logged.
  • final String? applyPath — The one string leaf Apply may write; null where the field is for chat only.
  • final AssistantDraft Function() draft — Snapshots the form’s draft.
• variable final assistantWhereProvider — Where the person is: derived from the rail, the selection and the project, published by the tabs and the field.
• class AssistantWhereController — Keeps [AssistantWhere]: the rail, page and entity derived, the tab and field published by their owners (§6.11a).
  • String? get shownStem — The full stem of the version the tabs show, the one [fieldGained] admits; null where no tabs report one.
  • void fieldGained(AssistantFieldAt field) — Holds [field], replacing any other, where it is of the version the tabs show on the project rail.
  • void fieldLeft(Object owner) — Clears the field only if [owner] holds it.
  • void tabSettled(Object owner, String stem, String? tab) — Takes the version the tabs show, by its full [stem], and their settled [tab].
• class AssistantShortcut — A press of an action’s AI icon on a form, or of its chip in the dock, so that the two animate as one and the dock runs the action an icon asks for (§6.11a).
  • const AssistantShortcut({required this.action, required this.from, required this.serial}) — The press of [action] [from] an icon or the chip, the [serial]th press of the session.
  • final String action — The action’s id.
  • final String from — What was pressed: field or section for the icon on a field or on a section’s title, chip for the dock’s chip.
  • final int serial — Counts the presses, so that the same action pressed twice is two states.
• variable final assistantShortcutProvider — The last press of an action’s icon or chip; null until one is pressed.
• class AssistantShortcutController — Carries each press (§6.11a): the icons and the dock listen; nothing is kept beyond the last press.
  • void press(String action, {required String from}) — Says [action] was pressed [from] — field, section or chip; logged assistant.shortcut.
• class AssistantRequest — What an action opens: the assistant, the action and the place of the gesture (§6.11a).
  • const AssistantRequest({required this.tag, required this.action, required this.where, this.target, this.draft}) — Binds [action] of [tag] to [where]; [target] and [draft] are a field action’s.
  • final String tag — The assistant’s package tag.
  • final AssistantAction action — The catalog’s action.
  • final AssistantWhere where — Where the person was at the gesture; immutable, so it stays that place while the person moves on.
  • final AssistantTarget? target — The field a field action works on, else null.
  • final AssistantDraft? draft — The field’s draft at the gesture, else null.
  • bool stillOnPage(AssistantWhere now) — Whether the person is still on the page this chat opened on, where its conversation is offered (§6.11a).
  • bool stillAt(AssistantWhere now) — Whether the person is still at the place this conversation opened: [stillOnPage], and for an action of level field, its field held, of the same stem and pair id.

lib/src/assistant_catalog.dart

• enum AssistantLevel — Where an action is offered: on a held field, on every field of a form section, on a section, on a rail, or anywhere; in the order the dock lists them.
  • values: field, formSection, section, rail, always
• class AssistantExport — What an action hands the model of the open film: a scope name or a pattern.
  • const AssistantExport()
• class ScopeExport — An export by one of the exchange’s registered scope names.
  • const ScopeExport(this.name)
  • final String name — The scope’s name, validated against the exchange’s registry.
• class PatternExport — An export by selector tokens, each with its projection.
  • const PatternExport(this.lines)
  • final Map<String, ProjectionSpec> lines — Each selector token → its projection, in file order.
• class ProjectionSpec — A pattern line’s projection: a named projection or a list of field paths.
  • const ProjectionSpec.named(String this.named)
  • const ProjectionSpec.paths(List<String> this.paths)
  • final String? named — One of everything, whole, summary, synopsis, frame, project_overview.
  • final List<String>? paths — One or more field paths, with no upper bound.
• class AssistantAction — One action of the catalog: what the person can ask the assistant at a place.
  • const AssistantAction({required this.id, required this.label, required this.prompt, this.finalize, this.models = const [], this.context = const [],…
  • final String id — Unique in the file, ^[a-z][a-z0-9-]{0,39}$.
  • final String label — A key of the package’s English strings.
  • final String prompt — The instruction sent to the model.
  • final String? finalize — The instruction that turns the answer into the field’s value; only on a field’s action.
  • final List<String> models — The action’s catalogue model ids; empty: the catalog’s defaults.
  • final List<String> context — What of the app’s state the action reads: activity.
  • final AssistantExport? export — What of the open film the action hands the model, or none.
  • final AssistantLevel level — Where the action is offered.
  • final String? rail — The rail’s validated name; null for an action offered anywhere.
  • final String? section — The section’s validated name; null above a section.
  • final String? effort — The reasoning effort the action asks of the model, low, medium or high; null: the model’s own default.
  • final String? asks — The question the dock asks itself, with no model call, where the project holds no summary (§6.11a); null: none.
  • bool get needsProject — Whether the action needs an open project: it exports something of it.
  • Set<String> get needsEntityOf — The type prefixes the page’s entity must have for the export (the intersection over its entity tokens, or a tags scope’s type); empty: no entity needed.
• class AssistantSection — A section of the project rail: its actions, its fields’ actions and its form sections’ actions.
  • const AssistantSection({this.actions = const [], this.fields = const {}, this.formSections = const {}})
  • final List<AssistantAction> actions — The section’s actions.
  • final Map<String, Map<String, List<AssistantAction>>> fields — Form section id → field id → actions; both ids the author’s text.
  • final Map<String, List<AssistantAction>> formSections — Form section id → actions, offered on every field of that form section; the id the author’s text.
• class AssistantRail — A rail section of the app: its actions and, on the project rail only, its sections.
  • const AssistantRail({this.actions = const [], this.sections = const {}})
  • final List<AssistantAction> actions — The rail’s actions.
  • final Map<String, AssistantSection> sections — Section name → section; project only.
• class AssistantCatalog — A catalog read whole: the assistant’s defaults and its actions by place.
  • const AssistantCatalog({this.format = 1, this.portrait, this.conversation = const [], this.models = const [], this.always = const [], this.rails =…
  • final int format — The format’s version: 1.
  • final String? portrait — The portrait’s path in the package, or none.
  • final List<String> conversation — The voice conversation providers: openai, grok; empty: chat only.
  • final List<String> models — The assistant’s default model ids.
  • final List<AssistantAction> always — The actions offered anywhere.
  • final Map<String, AssistantRail> rails — Rail name → rail.
  • Iterable<AssistantAction> get actions — Every action, for counts and the host’s checks.
• class AssistantCatalogRefused — A catalog refused whole: a format code and the location of the first problem.
  • const AssistantCatalogRefused(this.code, this.location, [this.value])
  • final String code, location — What refused the file, and where.
  • final Object? value — The value found at [location], logged whole beside the code; not part of equality.
• function AssistantCatalog readAssistantCatalog(String text, {required bool Function(String key) hasEnglishLabel}) — Reads [text], a catalog file, whole or not at all.
• class AssistantActionGroup — The actions of one level for a place.
  • const AssistantActionGroup(this.level, this.actions)
  • final AssistantLevel level — The level the actions are offered at.
  • final List<AssistantAction> actions — The level’s actions, in file order.
• function List<AssistantActionGroup> actionsFor(AssistantCatalog catalog, {required String rail, String? section, String? fieldSection, String? fieldKey}) — The actions for a place, in the owner’s order: the held field’s, its form section’s (offered on every field of it), the section’s, the rail section’s, then those offered anywhere; an empty level is left out.

lib/src/assistant_session_ledger.dart

• class Attribution — Which chat’s command a write was made for (§7.4): read from the Zone at a write door, never an argument.
  • const Attribution({ required this.command, required this.session, required this.assistantSession, this.operation, this.assistant, this.summary, }) — An attribution of a chat’s command, the host’s id and the command’s trusted name required.
  • final String command — The trusted source/name of the command, from the registry.
  • final String session — The app run’s command session (CommandRegistry.session).
  • final String? operation — The call’s operation, the host’s key per call.
  • final String assistantSession — The chat’s own id, the host’s action-<µs>-<n>.
  • final String? assistant — The selected assistant’s id.
  • final String? summary — The command’s summary argument, as handed.
  • static Attribution? get current — The attribution of the code running now, or null for a person’s write.
  • static T run<T>(Attribution attribution, T Function() body) — Runs [body] attributed to [attribution].
  • static T cleared<T>(T Function() body) — Runs [body] with no attribution: a person’s own write, inside a command’s scope or not.
  • Map<String, Object?> toLog() — The attribution as a log line’s data: every member as it is, the absent left out.
• enum WriteKind — How a write changed an entity (§7.4).
  • values: fork, create, patch, epoch, pick
• class EntityWritten — One write the controller made, published after it landed and never where nothing was written (§7.4).
  • const EntityWritten({ required this.stem, required this.kind, required this.projectKey, required this.author, this.before, this.after, this.from, t… — A receipt of one landed write.
  • final String stem — The version written, or for a pick the version picked (see the class).
  • final WriteKind kind — How the write changed the entity.
  • final String projectKey — The film the write was asked in, as projectKeyOf names it at the door’s entry.
  • final Author? author — The viewer the write went out as; null where there was none, and the writer refused.
  • final Map<String, dynamic>? before — The whole version as it was before an in-place write ([WriteKind.patch]); null for the other kinds.
  • final Map<String, dynamic>? after — The document as written; null for a pick, and for a flag whose file could not be read back.
  • final String? from — A pick’s version before: the viewer’s own pick, null where they had none.
  • final String? to — A pick’s version after: the version picked, official’s on a return to official, null where nothing is.
  • final Attribution? attribution — The chat the write was made for; null for a person’s write.
  • final String? epoch — An [WriteKind.epoch]’s token; [before] is then the entry it relabelled, null where it was appended, and [after] the entry as written.
• class WriteObserver — Hears every write the controller made, awaited by the write (§7.4): the default hears nothing.
  • const WriteObserver() — An observer that hears nothing.
  • Future<void> written(EntityWritten event) — Called once per write, after it landed; the write returns only when this has.
• class EntityWrittenBroadcast — The creates, patches and forks that landed (§7.4), told when their gesture has ended.
  • Stream<EntityWritten> get stream — The writes, in the order they landed.
• variable final entityWrittenProvider — The app’s one [EntityWrittenBroadcast]; its listener is the auto-generation of reference images.
• variable final assistantSessionsProvider — The live chats and their ledgers (§7.4); the app’s quit closes every one, an exit task while it lives.
• variable final assistantLiveChatsProvider — The ids of the chats open in this app (§7.4), as the ledgers publish them at each open and close: the tree’s Chats says archived of a record whose assistant_session is not among them (§8.2).
• class AssistantLiveChats — Holds [assistantLiveChatsProvider]’s ids, set only by [AssistantSessionLedgers].
• variable final writeObserverProvider — The one [WriteObserver] the controller awaits: the Assistant Sessions’ ledgers.
• class AssistantSessionLedgers — The ledger of each live Assistant Session, by the host’s id: the controller’s [WriteObserver] (§7.4), and the sessions’ close.
  • AssistantSessionLedgers(this._ref) — The ledgers over [_ref], none until a chat writes.
  • void Function(String id, String reason)? onCloseBegun — Told each new close’s session id and reason, once that close is kept in [_closes]: the dock ends a chat whose close it did not begin (§6.11a).
  • void Function(String id, String stem)? onFirstItem — Told once per session, the session id and its record’s stem, when its first content item — not a pick — is recorded: the dock moves to the record’s page from there (§6.11a).
  • String? get leaving — The reason of a [closeAll] under way — film_changed or quit —, else null: a chat opened meanwhile would outlive the film it was opened in, so the dock does not install one (§6.11a).
  • AssistantSessionLedger? of(String id) — The ledger of the session [id], once it wrote.
  • bool isLive(String id) — Whether the session [id] is live in this app: its ledger kept, so its record is still its own to write.
  • bool closeBegun(String id) — Whether the close of the session [id] has begun, whoever asked it; it stays true once that close has ended.
  • Future<bool> opened(AssistantSession session) — Takes [session] as open — a film left and the app’s quit close it with the others — and writes its record at once (§7.4): status: open, no item, its history, in the film open now as its viewer, so that a chat is rec…
  • Future<void> close(AssistantSession session, String reason, {Duration within = assistantCloseLimit}) — Closes [session] once, for [reason] — closed, reviewed, assistant_changed, film_changed or quit (§7.4): its turn cancelled and its work in flight let settle until the record’s slice before its deadline, [wit…
  • Future<void> closeSession(String id, String reason) — Closes the open chat [id] for [reason] ([close]): a review press on its record’s page (§7.4).
  • Future<void> closeAll(String reason, {required Duration within}) — Closes every open chat for [reason] at once and returns once each ledger is let go, within [within], its record closed where its last write landed by then: a close already under way is held to that deadline where it i…
• class AssistantSessionLedger — One Assistant Session’s writes, kept as its as record (Project Specification §12.7; §7.4).
  • final Attribution attribution — The opening’s ids, or the first write’s attribution: the session’s run, id and assistant.
  • final String started — When the chat opened, or its first write was heard, RFC 3339: the record’s started.
  • final String? action, entity — The record’s action and entity (§12.7): the catalog action the chat opened with, and the entity a field’s or form section’s action opened at — from the chat’s own request, never from its writes, whose first may be…
  • List<Map<String, Object?>> get items — The items as kept, in order.
  • List<Map<String, Object?>> get picks — The picks as kept, in order.
  • SetRecord? get record — The record as last written, or null before one landed.

lib/src/assistant_session_review.dart

• variable final sessionReviewProvider — The one door of an Assistant Session’s review (§7.4): [SessionReview] over the opened project’s controller.
• typedef typedef ReviewAnswer — What the review did with one item: its n, picked, discarded, refused or skipped, and a code where there is one to say (§7.4).
• class SessionReview — Picks and discards the items of the viewer’s own as record, as the person and never inside a chat (§7.4).
  • SessionReview(this._ref) — The review over [_ref]’s opened project.
  • Future<ReviewAnswer> pick(BatchStem record, int n, String side) — Picks one side of item [n] of [record]: left the version the session wrote, right a fork’s recorded base.
  • Future<List<ReviewAnswer>> pickAll(BatchStem record) — Picks the left side of every item of [record] in order of n, skipping one gone, discarded or decided.
  • Future<ReviewAnswer> discard(BatchStem record, int n) — Discards item [n] of [record] through the one door, setDiscarded: set aside, never deleted (§3.6).
  • Future<List<ReviewAnswer>> discardAll(BatchStem record) — Discards every item of [record] in reverse order of n, the periods last, each guarded as it comes: a refused item stays open and the rest continue.

lib/src/assistant_source.dart

• class AssistantSourceBinding — Holds the original source and the only content an unchanged captured draft may save.
  • AssistantSourceBinding({required Entity source, required Map<String, Object?> draft}) — Captures source identity and material content without reading or writing a file.
  • bool matches(Entity candidate) — Accepts the same source or its captured autosave, excluding only normal save normalization.

lib/src/assistant_voice.dart

• enum AssistantVoiceProvider — An explicit experimental voice route, independent of text and dictation preferences.
  • values: grok, openai
  • String get model — The actual provider model requested on the wire, never a text-model mapping.
  • String get platform — The existing provider credential identity.
• enum AssistantVoicePhase — The visible state of an owner-started spoken conversation.
  • values: ready, connecting, listening, thinking, speaking, finishing, ended, error
• enum AssistantTranscriptState — Whether an input transcript is arriving, awaiting completion, final or incomplete.
  • values: receiving, pending, complete, incomplete
• class AssistantVoiceMessage — A memory-only transcript entry, including whether generated speech was interrupted.
  • const AssistantVoiceMessage(this.id, this.role, this.text, { this.interrupted = false, this.transcription = AssistantTranscriptState.complete, }) — Keeps the provider item identity so partial transcripts update their own turn.
  • final String id — The provider item identifier, used only within this session.
  • final String role — Either user or assistant.
  • final String text — The generated or recognized text, never diagnostic data.
  • final bool interrupted — Whether some generated speech may not have been heard.
  • final AssistantTranscriptState transcription — The input transcript’s finality, independent of assistant response timing.
• class AssistantVoiceSession — An inertly opened conversation whose microphone and provider start only on Start voice.
  • AssistantVoiceProvider get provider — The frozen voice provider selected before Start.
  • AssistantVoicePhase get phase — The current listening, processing, playback or terminal state.
  • String? get error — A closed local error code, never provider text or a credential.
  • bool get muted — Whether microphone capture is released until the owner unmutes.
  • Duration get elapsed — The elapsed session time, running on through Finish’s drain; the clock a cap given to the session reads.
  • List<AssistantVoiceMessage> get messages — The transcript retained through End conversation and Finish until Close.
  • Map<String, int> get reportedUsage — Provider-reported token counts available so far, separate from a charge.
  • bool get started — Whether Start has already been used; no automatic retry or restart occurs.
  • bool get capReached — Whether the cap itself finished this session (§6.11), so that the dialog says so; a person’s Finish or End never sets it, and a new conversation is a new Start.
  • String? get microphoneBusyOwner — The owner that held the microphone when Start was refused with mic_busy, by its nonsecret name (§9.6).
  • AssistantApply? get apply — What Apply will do, set by the host on opening; null where nothing resolves (§6.11a).
  • set apply(AssistantApply? value)
  • AssistantReply? get finalized — How a revision-6 finalizer ended — completed with the proposal’s id or nothing, or an error’s code — and null before it ends; the host clears the id once the proposal is applied or discarded (§6.11a).
  • set finalized(AssistantReply? value)
  • void Function()? onDisposed — Told once when the session is disposed — its dialog closed — so the host ends what it holds for it (§6.11a).
  • Future<void> start() — Starts the one session only after the owner’s explicit gesture.
  • Future<void> setMuted(bool value) — Releases or reacquires the microphone while preserving this provider session.
  • Future<void> end() — Releases all live resources while retaining a readable transcript and draft.
  • Future<ConversationFinishReason> finish() — Stops input, commits what was said, drains the admitted captions for at most five seconds, then ends with the transcript frozen (§6.11); a session without a drain of its own ends at once.
• class AssistantVoiceService — The private voice service installed only in the dedicated native voice build.
  • static AssistantVoiceService? get current — The app’s optional native service; null preserves the existing text flow.
  • static void install(AssistantVoiceService? service) — Installs the native service, or null to retire it, without opening a session.
  • static Stream<void> get installations — Signals replacement to consumers that already read the service.
  • List<AssistantVoiceProvider> get providers — The routes supported on this device, in default-selection order, without checking keys.
  • void note(String event, Map<String, Object?> data) — Writes one line of the voice road’s log for a caller with no log of its own, the dialog (§6.11a).
  • AssistantApply? admissionOf(AssistantRequest request) — What Apply would do for a catalog action’s [request], said before Start: an inert read, null where nothing resolves or the service has no catalog road.
  • Future<AssistantVoiceSession> openAction(AssistantVoiceRequest request, AssistantPreferences preferences, AssistantVoiceProvider provider,) — Opens a catalog action’s conversation from the Start gesture; refused where the service has no such road.
• class AssistantVoiceRequest — A catalog action’s voice request: the action’s request and the providers it may speak through (§6.11a).
  • const AssistantVoiceRequest({required this.request, required this.providers}) — Pairs [request] with [providers].
  • final AssistantRequest request — The action’s request, with the place of the gesture.
  • final List<AssistantVoiceProvider> providers — The catalog’s voice providers that this device supports, in its order.

lib/src/auto_references_provider.dart

• class AutoActivity — One piece of Auto-generate’s work, as the dock’s activity line names it (§6.15).
  • const AutoActivity({required this.film, required this.stem, this.place = 'reference_images', required this.name, this.session, required this.phase,… — The work on [stem] of [film], named [name], for the chat [session] whose write started it.
  • final String film — The project key of the film the work is in.
  • final String stem — The stem of the entity whose picture it makes.
  • final String place — The media group the work renders into: reference_images, or a sheet’s group.
  • final String name — The entity’s name as the film reads when the line is set, else its stem: what the line names.
  • final String? session — The assistant session of the chat whose write started the work; null where the write named none.
  • final String phase — prompt while its prompt is waited for or written, render from the render’s preparation to its job’s end.
  • final String? job — The insertion job rendering it, once submitted.
  • final bool stopping — Whether a Stop was asked and its work is settling.
  • final String? problem — Why a Stop could not be confirmed, in words; the work still holds while it is set.
  • Map<String, Object?> get toLog — The line as the log carries it.
• class AutoReferences — The box as the dock draws it.
  • const AutoReferences({this.on = false, this.line, this.last, this.activity = const []}) — The box, the engine’s [line], how its [last] render went and its [activity].
  • final bool on — Whether the box is ticked.
  • final String? line — The sentence naming the work the box agrees to: the prompt writer’s route, the picture routes and their quotes; null until the engine has read them.
  • final String? last — How the last automatic reference image went, in a sentence; null before the first.
  • final List<AutoActivity> activity — The engine’s work under way, one line per entity and place, in the order it began.
• variable final autoReferencesProvider — The box, this person’s on this machine; default off.
• class AutoReferencesController — Keeps the box and carries the engine’s sentences to the dock (§6.15).
  • static const key — The preference’s key.
  • void Function()? onLineAsked — Asks the engine to read the line; set by the engine, none without one.
  • void Function()? onStopAsked — Stops all of the engine’s work; set by the engine, none without one.
  • void setOn(bool on) — Ticks or clears the box and keeps it, logged settings.keep.start and settings.kept.
  • void showLine(String? line) — Sets the [line] the box agrees to, null where the engine has none to name.
  • void showLast(String last) — Sets how the [last] automatic render went.
  • void showActivity(List<AutoActivity> activity) — Sets the engine’s [activity], the work under way, logged assistant.activity.changed at each change as it is set, whether or not a frame shows it (§6.15).
  • void askLine() — Asks the engine to read the line again, for the dock that draws it.
  • void stop() — Asks the engine to stop all of its work, for the dock’s Stop.

lib/src/automation_host.dart

• class AutomationHost — The seam the agent layer attaches to: what an agent may ask the running application, as an interface with a no-op default.
  • const AutomationHost()
  • static AutomationHost current — The host in use: the no-op one until [install] is called.
  • static void install(AutomationHost host) — Installs [host]; called by an agent entrypoint before the app’s main.
  • static final GlobalKey rootKey — The RepaintBoundary around the page (lib/app.dart), so a host can take a screenshot from the render tree on every platform.
  • static final GlobalKey windowKey — The RepaintBoundary above the navigator (lib/app.dart’s MaterialApp.builder): the whole view as Flutter draws it.
  • bool get isAvailable — Whether this host can act at all; the no-op host cannot.
  • bool get withholdsAccount — Whether the app leaves the sign-in hint alone, restoring no session of the person’s, while an agent build’s account mode restores the test account’s itself (§6.6).
  • void attach(ProviderContainer container) — Called once by main with the container every provider lives in.
  • Future<Map<String, Object?>> state() — What is on screen: the open project, the selection, the tab, the viewer — as data an agent can read.
  • Future<void> navigate(Selection selection) — Shows [selection], as a tree click would.
  • Future<void> setTab(String tab) — Opens the tab named [tab] on the current page.
  • Future<bool> tap(String identifier) — Taps the element carrying the semantics [identifier]; false when no such element is on screen.
  • Future<bool> setField(String stem, String key, String text) — Types [text] into the field [key] of the form editing [stem], through the form’s own setter (FieldRegistry), so the autosave, the identity lock and the stale refusal hold as for a person.
  • Future<Uint8List?> screenshot() — A PNG of the whole view ([windowKey], dialogs included), or null when the host cannot paint one.
  • Future<Object?> semantics() — The semantics tree as data: labels, identifiers, actions.
  • Future<List<String>> logTail({int lines = 50}) — The last [lines] of the application’s log.
  • Future<void> openProject(String? path) — Opens the project folder at [path], or the bundled sample when [path] is null — the project menu’s two doors.
  • Future<void> setViewer(String handle) — Sets the username through Settings’ own transition (§9.4): an empty handle is default, and one that is not a handle, or a change an open draft could not be written before, is refused and changes nothing.
  • Future<void> setLocale(String? code) — Chooses the language by its code (en, es) as Settings does, or the platform’s language when [code] is null.
  • Future<void> setTheme(String mode) — Chooses the theme as Settings does: system, light or dark.
  • List<String>? takePickedFiles() — The files an agent chose for the next file dialog, given once: null where none waits, so the dialog opens; empty where the agent cancels it.
• class NoOpAutomationHost — The host of every product build: answers “not available” to everything and does nothing.
  • const NoOpAutomationHost()

lib/src/browser_provider.dart

• variable final scriptOutlineProvider — The script as the viewer sees it, its lists as the viewer works on them ([workingScriptOutline]).
• variable final treeModelProvider — The tree of the current project; empty while loading.
• class ComparePair — A comparison a page is asked to open (§13.3): the two versions of its Compare, by stem.
  • const ComparePair({required this.left, required this.right}) — The pair [left] beside [right].
  • final String left — The viewer’s own version, in the left column, which they may write.
  • final String right — The version the page shows, in the right column.
• class BrowserState — Everything the browser page remembers.
  • const BrowserState({this.selection, this.nodeId, this.toggled = const {}, this.compare, this.edit})
  • final Selection? selection
  • final ComparePair? compare — The comparison the last navigation asked the page to open, until the next navigation.
  • final Object? edit — What asked the page to open on View/Edit, until the next navigation: a token per ask, so that a rebuild never asks again.
  • final String? nodeId — The highlighted tree row.
  • final Set<String> toggled — Rows whose expansion the user has flipped away from the default.
  • bool isExpanded(TreeNode node)
  • BrowserState copyWith({Selection? selection, String? nodeId, Set<String>? toggled})
• variable final browserProvider — The browser’s selection, highlighted row and expansion state (§8.1).
• class BrowserController — Resolves a landing and reveals the row representing the displayed version (§8.1).
  • void navigate(Selection? selection, {String? nodeId, ComparePair? compare, bool onEdit = false}) — The single entry point for showing something.
  • bool openCompare({required String left, required String right}) — Shows [right]’s page on Compare with [left] in its left column (§13.3): the door a write the app made opens a comparison by, once the write has been read back.
  • void pin(Selection selection) — Pins what is already on screen without moving the tree (§13.3).
  • void toggle(TreeNode node)
  • void setAllExpanded(bool expanded) — Expands or collapses every row with children.
• variable final treeFilterProvider — The sidebar filter text.
• class TreeFilterController
  • void set(String value)
• variable final navIndexProvider — Which page the navigation rail shows: Project at start.
• class NavIndexController
  • void set(int index)
• class NavIndex — The rail’s pages (lib/screens/dashboard.dart), each by a number that never changes: the rail draws them in its own order — Watch, Project, Activity, Share, GPU, Settings — and whatever reports a page names it ([name…
  • static const project — The open project, the page the app opens on.
  • static const activity — This device’s usage and the open film’s media being added.
  • static const settings — Settings.
  • static const watch — Tutorials and featured works.
  • static const share — The open film’s sends and receipts.
  • static const gpu — The GPU servers started for renders.
  • static String nameOf(int index) — The page’s name as the agent layer and the issue recorder tell it: watch, project, activity, share, gpu or settings.

lib/src/build_stamp.dart

• variable const int kBuildStampMaxLength — The longest stamp the website takes (Build.stamp).
• variable const int kAppVersionMaxLength — The longest version the website takes (DeviceRegistration.appVersion).
• function String runningPlatformName() — The platform this build runs on, in lower case: web, or the target platform’s name.
• function String appVersionWithBuild({required String version, required String build}) — 0.1.0+dev: the version and the build, at most [kAppVersionMaxLength].
• function String buildStamp({ required String version, required String build, required String commit, required String builtAt, required String platform, }) — The stamp of a build.
• function DateTime? builtMoment(String builtAt) — [builtAt] as a moment, or null unless it is an instant in UTC to the second.

lib/src/catalogue_provider.dart

• variable final catalogueProvider — The bundled model catalogue (Project Specification §14.6–§14.9), read once per run through the one reader and shared.

lib/src/children_controller.dart

• class AddedChild — The script’s operations — Add folder… / Add scene…, Remove from folder, and every move, of one row or of many — with what they answer.
  • const AddedChild(this.stem, {this.notListed})
  • final VersionStem stem
  • final Object? notListed — Null when the parent lists the new entry.
• class UnchangedChildrenException — A change of a children list that would change nothing.
  • UnchangedChildrenException(this.parentStem)
  • final String parentStem
• class ChildrenChangedMeanwhileException — A list of the script is not what it was when the person asked.
  • const ChildrenChangedMeanwhileException(this.parentStem)
  • final String parentStem
• class MovedChild — What [ChildrenController.moveChild] answers.
  • const MovedChild({this.notRemoved, this.alreadyListed = false})
  • final Object? notRemoved — What kept the entry in the list it was moved out of, after the destination took it; null when the move is whole.
  • final bool alreadyListed — The destination named the folder or scene already — perhaps under another spelling, a pin or none — so it took no second listing and the move was the removal alone: the caller says so, since the spelling that was move…
• class MovedChildren — What [ChildrenController.moveChildren] answers: what each list it wrote holds, as the writer handed it back.
  • const MovedChildren({ required this.toStem, this.landed, this.originsLanded = const {}, this.notRemoved = const {}, this.moved = const [], this.alr…
  • final String toStem — The list the entries were moved into.
  • final List<String>? landed — The destination’s list as the writer handed it back; null where the destination was not written.
  • final Map<String, List<String>> originsLanded — Each origin written, by stem, with its list as the writer handed it back.
  • final Map<String, Object> notRemoved — Each origin whose write was refused, by stem, with what refused it: its entries are still listed there.
  • final List<String> moved — The entries moved, in the order they were asked for, which is the order they land in.
  • final List<String> alreadyListed — The entries the destination named already, and so took no second listing.
  • bool get isWhole — Whether every list asked for was written: no origin refused.
• typedef typedef ChildBeside — Where a moved entry lands beside a row of its destination’s list: before, or [after], the [occurrence]-th listing of [entry].
• extension ChildrenController
  • Set<String> takenChildTagsNow(EntityType type) — The short names of [type] — folder or scene — spoken for, published or not.
  • String nextChildTag(EntityType type) — The short name a new folder or scene takes (§17): the next number over [takenChildTagsNow].
  • Future<AddedChild> addChild({ required EntityType type, required String tag, required String name, String? kind, required String parentStem, Author… — Add folder… and Add scene…: the viewer’s first version of a new folder or scene, listed at the end of [parentStem]’s children.
  • Future<void> removeChild({required String parentStem, required String entry, int occurrence = 0}) — Remove from folder: takes [entry] — the [occurrence]-th of that exact text — out of the children of [parentStem].
  • Future<MovedChild> moveChild({ required String entry, String? fromStem, int occurrence = 0, required String toStem, int? index, ChildBeside? beside… — Move up, Move down, Move to… and a drop: [entry] — the [occurrence]-th of that text in [fromStem]’s children — to [index] of [toStem]’s, [beside] a row of it, [by] places from where it is in its own list, or t…
  • Future<MovedChildren> moveChildren({ required List<({String? fromStem, String entry})> moved, required String toStem, ChildBeside? beside, int? ind… — Moves many rows — the marked ones — into [toStem]’s children in one gesture, in the order given.

lib/src/clipboard_asks.dart

• class ClipboardAsks — Shares one outgoing Clipboard.hasStrings among every caller that asks while it is outstanding (§4.2).
  • ClipboardAsks(this._forward, {required this.via}) — Asks that go out reach the platform through [_forward]; [via] names the install in the log.
  • final String via — Which install this is, binding or agent, on every start line: the log says the asks pass through it.
  • Future<ByteData?>? send(String channel, ByteData? message) — Sends [message] on [channel]: a clipboard ask through the shared slot, anything else straight to the forward.
• class ClipboardAsksMessenger — A [BinaryMessenger] whose sends pass through [ClipboardAsks]; handlers and inbound messages go to [delegate].
  • ClipboardAsksMessenger(this.delegate, {required String via}) — Wraps [delegate], its sends through a [ClipboardAsks] of its own whose log names [via].
  • final BinaryMessenger delegate — The messenger every message reaches in the end.

lib/src/command_registry.dart

• enum CommandCaller — Who called a command: the in-app voice conversation, the relay behind Remote control, or the text assistant.
  • values: voice, relay, text
• typedef typedef CommandHandler — What a command runs on a call.
• class Command — One thing the app offers a model: an MCP tool with its own handler (§7.3).
  • const Command({ required this.source, required this.name, required this.title, required this.description, required this.inputSchema, required this.…
  • final String source — builtin, or a plug-in’s tag.
  • final String name — The public kebab name inside [source].
  • final String title — The tool’s title, shown to a model’s person.
  • final String description — What the tool does, for a model choosing it.
  • final Map<String, Object?> inputSchema — A raw JSON Schema whose type is object, announced as it is.
  • final Map<String, Object?>? outputSchema — The schema of structured in a success, where the command gives one.
  • final Map<String, Object?>? meta — The MCP tool’s _meta, opaque, at most 8 KiB serialized.
  • final bool exposed — Whether the relay may call it; voice and text may call any command.
  • final bool effectful — Whether it takes session and operation and runs under the operation ledger.
  • final bool readOnly — Announced as readOnlyHint: the command changes nothing.
  • final bool destructive — Announced as destructiveHint: the command may remove something.
  • final CommandHandler handler — What a call runs once dispatch has admitted it.
  • final Set<String> codes — The fixed refusal codes its handler may answer, beside the registry’s own.
  • final Set<String> checkedByHandler — The arguments whose schema is announced and read at registration whole, but whose value the handler checks itself, against what it alone knows (an entity’s own type), with the detailed answer: the call’s schema check…
• class CommandResult — A command’s answer, in the shape of an MCP CallToolResult.
  • const CommandResult({this.content = const [], this.structured, this.meta, this.isError = false})
  • factory CommandResult.ok({Map<String, Object?>? structured, String? text, Map<String, Object?>? meta}) — A success with [structured] and, when given, [text] as its one text item.
  • factory CommandResult.refusal(String code, {Map<String, Object?> extra = const {}}) — A refusal: isError, the fixed [code] as structured.error and as the text.
  • final List<Map<String, Object?>> content — The MCP content items: text, an image, a link.
  • final Map<String, Object?>? structured — The machine-readable answer, structuredContent on the wire.
  • final Map<String, Object?>? meta — The result’s MCP _meta, opaque.
  • final bool isError — Whether this answers a refusal or a failure.
  • Map<String, Object?> toJson() — The MCP CallToolResult JSON.
• class CommandContext — What a handler is given for one call.
  • final String ref — The local call reference, c-<counter>: the only id the log carries.
  • final CommandCaller caller — Who called.
  • final Command command — The command being run.
  • final Map<String, Object?> args — The validated arguments, control fields included.
  • final DateTime? deadline — When the caller stops waiting, if it does.
  • final String authority — [CommandRegistry.authority] as it was at the call: the film the handler acts on.
  • final String? assistantSession — The chat that made the call, the host’s action-<µs>-<n>: set by the host, never a model’s argument; null for a caller that is no chat (the relay, the agent layer).
  • final String? assistant — The selected assistant’s id, beside [assistantSession].
  • Future<CommandRefusal?> admit() — The effect gate, called immediately before an effect: null when it may start, else the refusal to return.
  • CommandRefusal? check() — The refusal [admit] would answer now, or null, admitting nothing: for a read-only handler before outward work.
  • void observe(String outcome, {String? label}) — Raises the observation the root turns into a message, [label] the name it shows.
• class CommandRefusal — A refusal [CommandContext.admit] answers; the handler returns [result] unrun.
  • const CommandRefusal(this.code)
  • final String code — The fixed refusal code.
  • CommandResult get result — The refusal as the handler returns it.
• class CommandObservation — A command’s visible outcome, for the root’s message.
  • const CommandObservation({ required this.ref, required this.caller, required this.source, required this.name, required this.outcome, this.label, })
  • final String ref — The call’s local reference.
  • final CommandCaller caller — Who called.
  • final String source — The command’s source.
  • final String name — The command’s name.
  • final String outcome — ok, or the refusal’s code.
  • final String? label — The display text the command chose, such as an entity’s name, shown and logged.
• class CommandValidator — The JSON Schema check the root injects, since the state has no schema library of its own.
  • String? unsupported(Map<String, Object?> schema) — A fixed code when [schema] uses something this validator cannot check, else null.
  • List<String> problems(Map<String, Object?> schema, Object? value) — Short path codes, never values, for each way [value] breaks [schema].
• class CommandAllowedKeys — A validator that also says, for each argument a schema does not take, the ones it does: a refusal carries them so that a model is told what to send instead (§7.3).
  • Map<String, List<String>> allowed(Map<String, Object?> schema, Object? value) — For each notAllowed path of [value] under [schema], the keys the object there takes.
• class NoCommandValidator — The inert validator: accepts every schema and every value.
  • const NoCommandValidator()
• class CommandRegistrationException — A registration [CommandRegistry.register] refused, with its fixed [code].
  • const CommandRegistrationException(this.code)
  • final String code — The fixed refusal code.
• class CommandRegistry — The one list of what the app offers a model, and its dispatch (§7.3).
  • static ChangeNotifier get changes — Notified whenever a command is registered or removed.
  • static Stream<CommandObservation> get observations — Each command’s visible outcome as it raises it.
  • static CommandValidator validator — Checks schemas at registration and arguments at a call.
  • static String session — This app run’s session, a UUID the root makes at start; empty refuses every effectful call.
  • static String Function() authority — An opaque digest of account, viewer and project, captured at each call.
  • static DateTime Function() clock — The clock deadlines and the ledger read.
  • static String instructions({String separator = '.'}) — The text the catalogue carries for a model: one English paragraph, not localised.
  • static List<Command> get all — Every command, in registration order.
  • static Command? find(String source, String name) — The command [source]/[name], or null.
  • static void register(Command command) — Adds [command], or throws [CommandRegistrationException] with name, duplicate, not-object, schema-unsupported or meta-too-large.
  • static void unregister(String source, [String? name]) — Removes every command of [source], or only [name] when given.
  • static Map<String, Object?> toolOf(Command command, {String separator = '.'}) — The MCP Tool announcing [command], named <source><separator><name>.
  • static Future<CommandResult> call(String source, String name, CommandCaller caller, Map<String, Object?> args, { DateTime? deadline, bool Function(… — Runs the command [source]/[name] for [caller]; every refusal is a [CommandResult], never a throw.
  • static void resetForTest() — Back to the inert defaults: no commands, no session, the default clock, validator and authority.

lib/src/community_groups.dart

• class GroupName — A group’s or a person’s public name: its id and its username.
  • const GroupName(this.id, this.username) — The name [username] of the community id [id].
  • final String id — The community’s id.
  • final String username — The username, in the one grammar (§5.6).
• class GroupMembership — One membership of one of the account’s identities: the group, the identity that holds it and its role.
  • const GroupMembership({required this.identityId, required this.group, required this.role}) — [identityId]’s membership of [group] as [role].
  • final String identityId — The account’s identity that is the member: every call about the group acts as it, never the primary.
  • final GroupName group — The group.
  • final String role — owner, admin or member.
  • bool get manages — Whether this role may read the roster and the group’s invitations and invite.
• class GroupMember — One member of a group’s roster, as an owner or an admin reads it.
  • const GroupMember(this.identity, this.role) — [identity] as [role].
  • final GroupName identity — The member’s public name.
  • final String role — owner, admin or member.
• class GroupInvitation — One invitation: to [group] where it is the target’s, of [target] as [role], how it stands, until [expiresAt].
  • const GroupInvitation({required this.id, this.group, required this.target, required this.role, required this.expiresAt, required this.state}) — An invitation of [target] to [group] as [role].
  • final String id — The invitation’s id.
  • final GroupName? group — The group, where the target reads it; null on a group’s own list.
  • final GroupName target — The invited person.
  • final String role — The role it offers.
  • final int expiresAt — When it lapses, in seconds since the epoch.
  • final String state — pending, accepted, revoked, expired or unavailable.
• typedef typedef GroupPage<T> — One page of a list and whether another follows at the next offset.
• typedef typedef GroupDetail — One group as a membership reads it: the members where [GroupMembership.manages], else none.
• class CommunityGroupsRefused — A refusal of a community call, by its code alone, with the website’s status where one answered.
  • const CommunityGroupsRefused(this.code, {this.status}) — A refusal under [code].
  • final String code — The refusal’s code, for the consumer to word.
  • final int? status — The HTTP status that carried it; null where nothing was sent or nothing answered.
• class CommunityGroups — The account’s groups and invitations (§6.6): each call answers its value or throws [CommunityGroupsRefused].
  • const CommunityGroups() — Creates a client without account or transport work.
  • static CommunityGroups get current — The installed client; [NoCommunityGroups] by default.
  • static void install(CommunityGroups client) — Installs [client] without calling it.
  • Future<GroupPage<GroupMembership>> groups({int offset = 0}) — The memberships of every identity of the account (GET /v1/community/self/groups).
  • Future<GroupMembership> create(String username) — Makes the group [username], owned by the account’s primary identity (POST /v1/community/groups).
  • Future<GroupDetail> group(GroupMembership membership, {int offset = 0}) — [membership]’s group’s roster, read as its identity (GET /v1/community/groups/{g}); empty for a member.
  • Future<GroupInvitation> invite(GroupMembership membership, String username) — Invites the person [username] as a member, as [membership]’s identity (POST /v1/community/groups/{g}/invitations).
  • Future<GroupPage<GroupInvitation>> invitations(GroupMembership membership, {int offset = 0}) — The group’s invitations, as [membership]’s identity, an owner’s or an admin’s (GET …/groups/{g}/invitations).
  • Future<GroupPage<GroupInvitation>> received({int offset = 0}) — The pending invitations to the account’s identities (GET /v1/community/self/invitations).
  • Future<GroupMembership> accept(String id) — Accepts the invitation [id], made to one of the account’s identities (POST …/self/invitations/{i}/accept).
  • Future<void> decline(String id) — Declines the invitation [id] (POST …/self/invitations/{i}/decline).
  • Future<void> leave(GroupMembership membership) — [membership]’s identity leaves its group (DELETE /v1/community/groups/{g}/members/{identity}).
• class NoCommunityGroups — The client of a build that installed none: every call is refused not-signed-in; nothing is sent.
  • const NoCommunityGroups() — The inert client.

lib/src/comp_poster.dart

• variable final compPosterProvider — Posts comps; the default answers not available, the app’s composition posts to the comps service.
• class CompPoster — Posts a comp in two calls, so the posting is written before any request (§6.17).
  • Future<CompPosting> prepare(SetRecord comp) — Composes [comp]’s draft and prepares its bundle, with no request; throws a [CompPostException] on a refusal.
  • Future<CompPostOutcome> publish(CompPosting posting) — Sends [posting]’s bundle — the one prepared, else prepared again from the frozen posting — and answers its outcome.
  • Future<CompPostOutcome> check(String revision) — Reads the state of [revision] under the signed-in account.
  • Future<CompPostOutcome> abandon(String revision) — Deletes [revision]’s staging; a revision published first answers its published receipt.
  • Stream<double> get progress — The running publish’s progress, 0 to 1: a broadcast stream, listened to by as many as like.
  • void cancel() — Cancels the running publish.
• class CompPosting — What a post is of, frozen before any request: the record’s posting (§6.17).
  • const CompPosting({ required this.stem, required this.revision, required this.slug, required this.project, required this.account, required this.dra… — A posting of its parts.
  • final String stem — The comp record’s stem.
  • final String revision — The revision the service knows the post by.
  • final String slug — The comp’s address segment.
  • final String project — The project’s tag the comp is filed under.
  • final String account — The account signed in when the post was prepared, the one every later call runs as.
  • final Map<String, Object?> draft — The comp’s JSON as handed to the assembler.
  • final Map<String, String> sources — Each media’s source id to the local file it was prepared from, so the same revision can be prepared again.
• enum CompPostState — A revision’s state as the service answers it.
  • values: receiving, published, cancelled
• class CompPostOutcome — The outcome of a publish, a check or an abandon: the receipt’s state, or a refusal’s code and detail.
  • const CompPostOutcome({required this.revision, this.state, this.url, this.code, this.detail, this.definite = false}) — An outcome of its parts.
  • final String revision — The revision answered for.
  • final CompPostState? state — The receipt’s state; null on a refusal.
  • final String? url — The comp’s public address, once published.
  • final String? code — The refusal’s code; null where a receipt answered.
  • final String? detail — What the service said beside the code, for the log and the person’s detail.
  • final bool definite — Whether the revision’s fate is known: published, cancelled, or refused for good; else the post stays unsettled.
  • bool get published — Whether the revision is published at [url].
• class CompPostException — A refusal before any request: the comp could not be prepared.
  • const CompPostException(this.code, {this.detail}) — A refusal with its [code] and [detail].
  • final String code — The stable code the page says in its own words.
  • final String? detail — What was refused and why, for the log.
• class UnavailableCompPoster — The poster where none is installed: every call answers not available.
  • const UnavailableCompPoster() — The poster of a build without the comps service.

lib/src/consts.dart

• variable const String kAppName
• variable const String kDefaultViewerHandle — The username every write is made as where none is chosen (§9.4): a literal author handle, valid under the format’s rule, and nobody’s account.
• variable const bool kDevelopmentModeAvailable — Whether this build has development mode at all.
• variable const String kFilmOpenDomain — The website the app links to and names: filmopen.ai.
• variable const String kFilmOpenSiteUrl — [kFilmOpenDomain] as the site’s root URL, without a trailing slash.
• variable const String kFilmOpenDocsDomain — The documentation site, which is not the website: docs.filmopen.ai, and in a build that has development mode ([kDevelopmentModeAvailable]) its development site, where a page is published before the released docs have it.
• variable const String kFilmOpenDocsUrl — [kFilmOpenDocsDomain] as the documentation site’s root URL, without a trailing slash.
• variable const String kSampleProjectAsset — The bundled sample project, Appendix B of the specification.
• variable const String kSampleProjectName — Its title, for the project list before it has been loaded.
• variable const String kSampleLibraryAsset — The seed copy of the shared library (§14.5): models, platforms and plugins, copied to the app’s own library folder on first run.
• variable const String kCatalogueRoot — Where the model catalogue is bundled (the application’s assets).

lib/src/core_commands.dart

• variable final commandObservationsProvider — Each command’s observation as it is raised: what the root’s message hears (§7.3).
• function void registerCoreCommands(ProviderContainer container) — Registers the app’s own commands, builtin/*, acting on [container]’s providers through a person’s doors (§7.3).
• variable const entityScope — The export scope of an entity or its epochs, at the working version each change would start from.
• typedef typedef CommandEntity — What [resolveCommandEntity] answers: the entity and how it was found, or none and not-found.
• function CommandEntity resolveCommandEntity(FilmProject project, Author? viewer, String id) — The entity a command’s [id] names for [viewer], with how it was found (stem, exchangeId), else not-found.

lib/src/deadline.dart

• variable const Duration serverDiscoveryBudget — The admission-inclusive whole-operation budget for server discovery.
• class Deadline — A pure operation deadline whose child limits consume the parent’s remaining time.
  • Deadline({required DateTime startedAt, required Duration budget, DateTime Function()? clock}) — Starts before admission, using an injectable clock without a timer or platform listener.
  • final DateTime startedAt — The start of the admitted operation, in UTC.
  • final Duration budget — The whole operation’s budget, rather than a fresh per-request timeout.
  • DateTime get deadline — The absolute instant a host threads into its existing call-frame deadline.
  • Duration get remaining — The nonnegative remaining budget, bounded by the parent’s and zero after cancellation.
  • bool get isCancelled — Whether this operation or any ancestor was explicitly cancelled.
  • Future<void> get whenCancelled — Completes on this operation’s or an ancestor’s cancellation, without starting a timer.
  • void cancel() — Cancels this operation and descendants once, without cancelling ancestors or siblings.
  • Deadline child(Duration limit) — Starts a child now with at most the requested limit and the parent’s remaining budget.

lib/src/device_registration.dart

• class DeviceAccount — Who is signed in, as the registration needs it.
  • const DeviceAccount({required this.id, required this.anonymous, required this.accessToken})
  • final String id — The account’s id: the subject of its token, which the proof names.
  • final bool anonymous — An anonymous sign-in registers no device: it is a session nobody can return to (the website’s contract).
  • final Future<String?> Function() accessToken — The session’s access token when the request is made — refreshed first when it is past its hour, since a restored session often is — or null when there is no session any more.
• class DeviceRegistration — Where a sign-in and a sign-out are told.
  • const DeviceRegistration()
  • static DeviceRegistration current — The registration in use: [NoDeviceRegistration] until an entrypoint installs another.
  • static void install(DeviceRegistration registration) — Installs [registration]; called by an entrypoint before the app runs.
  • void signedIn(DeviceAccount account) — [account] is signed in: at a sign-in, and when a launch restores the session.
  • void signedOut() — Nobody is signed in any more.
  • bool get registers — Whether a sign-in on this build would register the device at all.
  • String? get slug — The device’s permanent name as the website answered it for whoever is signed in, or null: none claimed yet, nobody signed in, or a build that registers none.
  • Future<String> claim(String slug) — Claims [slug] as the device’s permanent name by registering again with it in the signed body.
• class NoDeviceRegistration — The registration of a build that installed none: it does nothing.
  • const NoDeviceRegistration()

lib/src/drafts.dart

• class DraftWriteContext — The write policy of a change made below a form.
  • const DraftWriteContext({required this.identity, required this.save})
  • final Object identity
  • final Future<Entity?> Function(Entity entity, Map<String, dynamic> json) save — Writes [json] over [entity] through the bound writer and answers the file it wrote, or null where it wrote none.
• class DraftWriteConflictException — A pending change belongs to a different bound writer.
  • const DraftWriteConflictException()
• class OpenDraft — A form’s draft while its page is open.
  • String get stem — The stem of the file this is the draft of.
  • String? get projectKey — The film the form was built for; null only for unbound test seams.
  • Future<bool> settle() — Waits for a write in flight, then writes what is pending.
  • Map<String, dynamic>? get pending — The whole document this draft would write — the file as it was read with what is typed on top — while something is pending, and null when nothing is.
  • Map<String, dynamic> get snapshot — A deep copy of the current document, including a write in flight and newer typing.
  • void adopt(Entity written) — Takes the writer’s hand-back of a write made from this draft as the base of its next write.
  • Future<Object?> apply(void Function(Map<String, dynamic> draft) change, {String? key, bool reseed = false, DraftWriteContext? writeContext}) — Takes [change] as it takes a keystroke, and writes it now.
• class EditableDraft — An open draft a card below the forms edits as the page’s own: it changes the draft as a keystroke does, and says when the draft changed, so that the card shows what the form shows.
  • void change(void Function(Map<String, dynamic> draft) apply, {String? key, bool reseed = false}) — Applies [apply] to the draft as a keystroke, the autosave writing it in its turn; [key] is the key that changed, for the draft’s observers, and [reseed] has the form’s boxes read the draft again.
  • Listenable get listenable — Notifies whenever the draft changes, typed or applied.
• class DraftRefusal — What an open draft says about its last write: the error that left it unwritten, for an action [OpenDrafts.settleOrRefusal] stopped to say why in the save’s own words.
  • Object? get refusal — The error of the write that left this draft unwritten, or null where it is clean, waiting or writing.
• enum DraftChangeKind — What happened to the open drafts: a form opened, went away, or moved to another file (§6.14).
  • values: added, removed, moved
• class DraftChange — One change of the open drafts, heard by the sync, which sends a document once its form is left (§6.14).
  • const DraftChange(this.projectKey, this.kind) — Names the film of the draft that changed and how.
  • final String? projectKey — The film the draft was built for; null only for unbound test seams.
  • final DraftChangeKind kind — Whether the draft was added, removed or moved to another file.
• class OpenDrafts — The drafts open across the app, and the writes no form waits for any more.
  • static bool get idle — Whether nothing is open and nothing is being written: no draft for [settleOpen] to write first.
  • static void add(OpenDraft draft)
  • static void remove(OpenDraft draft)
  • static void moved(OpenDraft draft) — Says that [draft] now edits another file: the file it left may be sent (§6.14).
  • static Stream<DraftChange> get changes — Every draft added, removed or moved to another file, heard after the change (§6.14).
  • static Stream<void> get writesSettled — An event each time the last tracked write ends, so that a send held for it can go (§6.14).
  • static bool get writesPending — Whether a draft’s write is in flight: no document is read for sending meanwhile (§6.14).
  • static bool openIn(String projectKey) — Whether a form is open on a file of the film [projectKey].
  • static OpenDraft? of(String stem, {String? projectKey}) — The draft open on the file [stem], if a form is.
  • static void track(Future<void> write) — A write in flight, waited for by [settleOpen] and by every pass of [settleUntilQuiet] until it completes: a draft’s own as it starts, and one left behind by a form gone.
  • static Future<bool> settleOpen() — Settles every draft ([OpenDraft.settle]) and waits for every write left behind, for an action that reads files the way they are on disk — a fork copies one (§13.1).
  • static Future<Object?> settleOrRefusal() — Settles every draft as [settleOpen] does, and answers why one could not be written, or null where every one is clean afterwards.
  • static const maxSettlePasses — The most passes [settleUntilQuiet] makes: typing that outruns five writes in a row is still being typed, and what waits on it does not go on under it.
  • static Future<Object?> settleUntilQuiet() — Settles every draft as [settleOrRefusal] does, pass after pass while one leaves something to write — a form opened meanwhile, or one typed into after its own write — up to [maxSettlePasses] passes, so that nothing typ…
• class DraftsNotSettledException — An open draft could not be written, so an action that writes beside it — an add, a remove, a move — did nothing.
  • const DraftsNotSettledException()
• class DraftObserver — Hears every change a form’s draft takes: the entity being edited, the key that changed, and the draft’s value at that key after the change.
  • void onChange(Entity entity, String? key, Object? value) — [value] is a deep copy, so an observer never writes into a draft.
• class DraftObservers — The observers of every draft; empty in the product.
  • static void add(DraftObserver observer)
  • static void remove(DraftObserver observer)
  • static void notify(Entity entity, String? key, [Object? value]) — Tells every observer, copying [value] once per observer, so that what one does with it cannot reach another or the draft.

lib/src/entity_commands.dart

• variable const assistantDraftPrefix — What the label of the assistant’s draft begins with (§7.3).
• function Future<T> attributed<T>(CommandContext context, Future<T> Function() write) — Runs [write], one write [context]’s command authors, attributed to the chat that called (§7.4).
• function String assistantDraftLabel(String? summary) — The label of a version the assistant’s write creates: ai: and the first four words of [summary], cut at a word boundary to the format’s 32 characters; ai: draft where none is given (§7.3).
• function Entity? assistantDraftOf(FilmProject project, Author viewer, EntityVersions versions) — The assistant’s draft of [versions] for [viewer]: the viewer’s newest own version where its label begins with [assistantDraftPrefix] and the viewer has neither picked it nor made it official, else null (§7.3).
• enum WorkingBase — Where the assistant’s next change of an entity lands: in the person’s draft, or on a fork of their version in use.
  • values: round, inUse
• typedef typedef WorkingVersion — What [workingVersion] answers: the version a change is made from, where it lands, and why, as a fixed code.
• function WorkingVersion workingVersion(FilmProject project, Author viewer, EntityVersions versions) — The version the assistant’s change of [versions] is made from, for [viewer], the person (§7.3).
• function ({EntityVersions? versions, String resolved}) versionsNamed(FilmProject project, String id) — The versions at one epoch that a command’s [id] names, with how it was named (stem, exchangeId), else none and not-found (§7.3).
• function void registerEntityCommands(ProviderContainer container) — Registers the assistant’s write path, builtin/update-entity, builtin/create-entity, builtin/move-entity and builtin/declare-epoch, on [container]’s providers, for every caller alike (§7.3).
• variable const createTypes — The types create-entity makes (§7.3): the library’s — an outfit through its character’s own door, its tag allocated there —, and a scene or a folder, listed in the script.

lib/src/entity_patch.dart

• class EntityWriteBinding — The film and write policy an external change began with.
  • EntityWriteBinding({required this.project, required this.viewer, required this.guards})
  • final FilmProject project
  • final String projectKey
  • final Author? viewer
  • final Guards guards
  • Object get identity — Compatible changes may share a pending draft snapshot.
• class EntityPatchResult — A refused patch exposes a stable code to jobs and preserves the writer’s original refusal for existing form and children callers.
  • const EntityPatchResult.success()
  • const EntityPatchResult.refused(this.code, this.refusal)
  • final String? code
  • final Object? refusal
  • bool get succeeded
• class ProjectNotOpenException — The film is closed or a different source has replaced it.
  • const ProjectNotOpenException()
• class EntityChangedMeanwhileException — A taken re-read does not contain the change that was requested.
  • const EntityChangedMeanwhileException()
• extension EntityPatches — The single door for a change made beside a form.
  • EntityWriteBinding bindEntityWrite() — Capture before the first await, including for a children action with two writes.
  • Future<EntityPatchResult> patchEntity(String projectKey, String stem, void Function(Map<String, dynamic> json) change, { String? key, bool reseed =… — Applies one change at a time per film and version, one gesture of its own (§7.5).

lib/src/entity_restore.dart

• enum RestoreOutcome — What a Restore from the recycle bin ended in (Project Specification §7).
  • values: restored, forkedPicked, forkedNotPicked
• class RestoreRefused — A Restore refused before anything was written, with its fixed code: no-viewer, read-only, drafts-unsettled, gone or not-deleted.
  • const RestoreRefused(this.code)
  • final String code
• function Future<({RestoreOutcome outcome, String stem})> restoreEntity({ required ProjectController controller, required Entity entity, required Author? vie… — Restores [entity] from the recycle bin for [viewer], by one rule with two doors (§7).

lib/src/exit_tasks.dart

• class ExitTasks — Work that must end before the app does, beside the open drafts ([OpenDrafts]).
  • static void add(Future<void> Function() task) — Runs [task] before the app exits, until [remove] takes it back.
  • static void remove(Future<void> Function() task)
  • static Future<void> runAll() — Runs every task at once and waits for them all.

lib/src/field_registry.dart

• typedef typedef FieldSetter — Types text into one field of a form, named by the key the field owns, as the field’s own onChanged would.
• class FieldRegistry — The forms open for editing, by the stem of the file each edits, so an agent (AutomationHost.setField) can type into a box the way a person does.
  • static Iterable<String> get stems — The stems of the forms open for editing, each once, however many setters it holds.
  • static void register(String stem, FieldSetter setter) — Adds [setter] for [stem], beside any setter already there; the same setter twice is held once.
  • static void unregister(String stem, [FieldSetter? setter]) — Removes [setter] from [stem] — or every setter of [stem] when none is given.
  • static bool setField(String stem, String key, String text) — Types [text] into the field [key] of the form editing [stem], asking each of its setters until one answers.

lib/src/import_apply.dart

• typedef typedef ImportRead — How Apply reads the app’s providers: a Ref’s, a WidgetRef’s or a container’s read.
• class ImportBindingChangedException — The handle or development mode changed since the proposal was made: nothing is written as another viewer.
  • const ImportBindingChangedException()
• class ImportProposalDroppedException — The proposal no longer belongs to the film open now, or to its viewer, and was dropped.
  • const ImportProposalDroppedException()
• class ImportApplyInFlightException — An Apply is still running: a second one, of any proposal, would plan on the index before its writes.
  • const ImportApplyInFlightException()
• class ControllerImportWriter — Writes a reviewed import through the controller’s own doors as the proposal’s viewer (§6.18).
  • ControllerImportWriter(this._read, {required this.film, required this.viewer, required this.guards})
  • final String film — The film’s key every stage must still find open.
  • final Author? viewer — The viewer the proposal was made and reviewed for.
  • final Guards guards — Development mode’s policy as the plan was made under it.
• class ImportApplyAnswer — What Apply answered: a redrawn review, the written result, or a refusal before anything was written.
  • const ImportApplyAnswer()
• class ImportRedraw — The plan moved since the review: nothing was written and the proposal now holds [proposal]’s plan to review again.
  • const ImportRedraw(this.proposal)
  • final ImportProposal proposal
• class ImportApplied — The plan was written as reviewed: each change’s outcome, and the proposal holding what is left to review.
  • const ImportApplied(this.proposal, this.result)
  • final ImportProposal proposal
  • final ImportResult result
• class ImportApplyRefused — Nothing was written: a draft refused with its own reason, the proposal was dropped, or an Apply is running.
  • const ImportApplyRefused(this.refusal)
  • final Object refusal
• function Future<ImportApplyAnswer> applyImportProposal(ImportRead read, ImportProposal reviewed) — Apply on [reviewed], the proposal as the person was shown it (§6.18): the one door the review and the assistant’s dialog call.
• getter bool get importApplyRunning — Whether an Apply is running now, for a dialog to hold its own button while it does.

lib/src/import_proposals.dart

• class ImportOrigin — Where an import proposal came from: the plug-in, its function and, for the assistant, its operation (§6.18).
  • const ImportOrigin({required this.plugin, required this.function, this.operationId})
  • final String plugin — The plug-in’s tag, as its door passes it: the review names the plug-in by it.
  • final String function — The function whose call proposed the import.
  • final String? operationId — The operation the proposal belongs to, which takes it away when it ends.
• class ImportProposal — One import waiting for the person: the document, the plan as they review it and the stages already written.
  • ImportProposal({ required String id, required Map<String, Object?> document, Map<String, Object?>? base, required ImportOrigin origin, required Str… — Freezes copies of the documents, JSON values only, so that no edit of a caller’s maps changes what was reviewed.
  • final String id — The proposal’s id, the one a door answered with.
  • final Map<String, Object?> document — The import document as proposed.
  • final Map<String, Object?>? base — The export the document was made against, where the plug-in named one.
  • final ImportOrigin origin — The plug-in call that proposed it.
  • final String film — The film’s key (projectKeyOf) the proposal was made in.
  • final Author? viewer — The viewer the plan was made for, and the only one it is written as.
  • final Guards guards — Development mode’s policy the plan was made under, and the only one it is written under.
  • final DateTime proposedAt — When the door held it.
  • final ImportPlan plan — The plan the person is shown; Apply writes only where a plan recomputed then is the same.
  • final Map<ExchangeId, Map<ImportStage, String?>> stages — The stages earlier applies completed, by change, with the stems they made: what Apply again resumes from.
  • final bool deferred — Whether the person put it aside with Later: the browser offers it again only when asked (§9.3).
  • ImportProposal withReview(ImportPlan plan, {Map<ExchangeId, Map<ImportStage, String?>>? stages}) — The same proposal with another reviewed plan and the stages written so far.
  • bool belongsTo(String? film, Author? viewer) — Whether the proposal still belongs to the film open now, as the viewer of now.
• class ImportProposals — The import proposals waiting for the person, and the exports an operation keeps (§6.18, §7.1): a seam.
  • static Listenable get changes — Notified after every change of the proposals; not on a drop at read, which the reader already sees.
  • static void add(ImportProposal proposal) — Holds [proposal] for the person, after any held before it; one with the same id is replaced in its place.
  • static void replace(ImportProposal proposal, {ImportProposal? expected}) — Replaces a held proposal with [proposal], keeping its place; one discarded meanwhile stays discarded, and where [expected] is given, one replaced meanwhile by another stays as it is.
  • static void defer(ImportProposal shown) — Puts [shown] aside with Later, after every other held proposal, so that the next one asked for is another; one let go or replaced since it was shown is not put aside, and a new document under its id is a new proposal.
  • static void discard(String id) — Lets the proposal [id] go, written or not.
  • static List<ImportProposal> current({required String? film, required Author? viewer}) — The proposals of [film] for [viewer], in the order they came; every other one is dropped.
  • static ImportProposal? of(String id, {required String? film, required Author? viewer}) — The proposal [id] where it belongs to [film] and [viewer]; dropped and null where it does not.
  • static void retainExport(String operationId, String exportId, Map<String, Object?> document) — Keeps an export [document] under [exportId] for the operation [operationId] until it is released.
  • static Map<String, Object?>? exportOf(String operationId, String exportId) — The export [exportId] the operation [operationId] kept, or null.
  • static void release(String operationId) — Ends what the operation [operationId] kept, when it is cancelled, fails or ends with nothing to propose: its exports and its proposals.
  • static void clear() — Forgets every proposal and every kept export.

lib/src/incoming_links_provider.dart

• variable final incomingLinksProvider — The one door for links the operating system hands the app, as the widgets reach it.

lib/src/insertion_provider.dart

• typedef typedef MachineSettingsSnapshot
• class ContainerInsertionEnvironment — The app supplies its settings snapshot without making state depend on host.
  • ContainerInsertionEnvironment(this.container, {required this.machineSettings, this.maxBytes})
  • final ProviderContainer container
  • final MachineSettingsSnapshot machineSettings — Null while the plug-ins’ settings are read again, when a job is refused settingsLoading (§6.13).
  • final int? maxBytes — The import cap: the web’s, or null on the desktop, which has none.
• variable final insertionServiceProvider
• variable final jobViewsProvider — Subscribe before seeding, so a remounted card cannot miss existing work.
• variable final filmReplacedRendersProvider — How many producers’ jobs have ended filmClosed this session — a render finished for a film with no folder that another film replaced, with nothing written — so that the app can say so as it happens (§6.13), the job…
• function InsertionService createApplicationInsertionService(ProviderContainer container, { String? directory, required MachineSettingsSnapshot machineSettin… — Constructs inert insertion ownership with eight active attempts and a separate film mutation gate.
• class InsertionAppBinding — Owns opening notifications and the bounded exit task, independently of pages.
  • InsertionAppBinding(this.container, this.service, {required this.settingsChanges, required this.settingsReady})
  • final ProviderContainer container
  • final InsertionService service
  • final Listenable settingsChanges
  • final bool Function() settingsReady
  • Future<void> close({Duration grace = const Duration(seconds: 10)})

lib/src/integration_providers.dart

• variable final accountSnapshotProvider — Observes the installed public account snapshot without initializing an account.
• variable final providerFundingProvider — Observes the funding resolver’s revision without querying funding during build.
• variable final microphoneOwnerProvider — Observes the current microphone owner without opening audio capture.
• variable final mediaEntryActionsProvider — Observes the media action registry without invoking its registered consumers.
• variable final nativeConversationSupportProvider — Observes native conversation support without opening or admitting a session.

lib/src/job_report_log.dart

• function void logJobReport(String prefix, String id, String code, [String? error, Map<String, Object?>? data]) — Writes a jobs engine’s report to the log as <prefix>.<code> with the job’s id (§6.12).

lib/src/launch_arguments_provider.dart

• variable final launchArgumentsProvider — The command line the process was started with, supplied by main; empty in tests and where the platform passes none.

lib/src/lending.dart

• function String usdOfCents(int cents) — [cents] whole US cents as the list keeps a price ([SharedOffer.usd]): 2 → '0.02', 20 → '0.2', 100 → '1'.
• function int? centsOfUsd(String usd) — The whole cents of [usd] as [usdOfCents] writes it, or null for a text not of that shape.
• class SharedOffer — One offer this computer shares, as the person fixed it (§6.11, Lending): a plug-in’s sharing operation on one server, one stack with the options the person chose on it, named and priced.
  • const SharedOffer({ required this.id, required this.tag, required this.function, required this.model, this.server, required this.stack, this.params… — An offer; [params] is kept as given.
  • final String id — The offer’s id on the website: a UUID made once on this computer and kept for good.
  • final String tag — The plug-in’s tag.
  • final String function, model — The sharing operation’s function and model, as the plug-in’s manifest declares them.
  • final String stack — The plug-in’s way of running the model, as its options named it.
  • final Map<String, Object?> params — The options the person fixed on the stack, by the stack’s own option names: {resolution: '1024x1024'}.
  • final String name — The person’s name for it, made from the stack’s label and the fixed options: 8 GB Quality · 1024x1024.
  • final String usd — The price of one unit in US dollars, an exact decimal of whole cents with no trailing fractional zero: '0.02', '0.2'; '0' is free.
  • final bool enabled — Whether the person has it on: only an enabled offer is published.
  • Map<String, Object?> toJson() — The offer as the list keeps it.
  • static SharedOffer? fromJson(Object? json) — An offer as [toJson] wrote it, or null for an entry not of that shape — every build on a machine shares the preferences, so a value read may be anything.
  • static List<SharedOffer> listOf(Object? json) — The offers of a stored list: each entry of the shape, the rest left out; nothing where [json] is not a list.
• class LendingRefused — The website’s refusal of a lending operation, by its code alone — or unreachable where nothing answered and malformed where the answer was not of the design’s shape.
  • const LendingRefused(this.code) — A refusal under [code].
  • final String code — The error envelope’s code, never its words.
• class LendingJobSummary — One job as the website summarises it, closed to what the supplier’s loop and the requester read.
  • const LendingJobSummary({ required this.id, required this.offerId, required this.state, this.priceCents, this.resultAvailable = false, this.closeRe… — A job [id] of the offer [offerId], in [state] (requested, accepted, …).
  • final String id
  • final String offerId
  • final String state
  • final int? priceCents — The price frozen at preparation, in US cents.
  • final bool resultAvailable — Whether the result is published and still readable, whatever the money’s state.
  • final String? closeReason — refused, failed, cancelled or expired, for a job closed without a result.
  • final String? failCode — The supplier’s bounded code for a refusal or a failure.
  • final int? retrieveUntil — Until when the result’s bytes may be read, in Unix milliseconds.
• class LendingJob — A job as a participant reads it: its summary, the frozen declaration, the input and, once published, the result.
  • const LendingJob({required this.summary, this.declaration, this.input, this.result}) — A job of [summary], with the [declaration], [input] and [result] the website retains for it.
  • final LendingJobSummary summary
  • final Map<String, Object?>? declaration
  • final Object? input — The buyer’s input as the website keeps it: any JSON, opaque to the website, for the supplier to judge.
  • final Map<String, Object?>? result — The supplier’s result, a JSON object opaque to the website; its media travel inside it by URL.
• class LentOffer — One published offer this account may render on, as discovery lists it: the declaration’s plug-in, its configuration and rates, and the website’s derived facts.
  • const LentOffer({ required this.offerId, required this.version, required this.pluginId, required this.pluginVersion, required this.configuration, r… — The offer [offerId] at [version], declared for [pluginId] at [pluginVersion].
  • final String offerId
  • final String version
  • final String pluginId
  • final String pluginVersion
  • final Map<String, Object?> configuration — The declaration’s public configuration: for a render, its function, model and unit.
  • final bool own — Offered by this same account.
  • final bool free — Free to this account — any of its persons named by the lender, or in a group the lender names — advisory until preparation.
  • final bool available — Its supplier is available now.
  • final bool published — This version is the offer’s published one.
  • final String? lender — The lender’s public username, its account’s primary one; null where it has claimed none.
• class AudienceSettings — Who may use this account’s published offers (/v1/lending/settings, §6.11, Lending): the website’s revision of the setting, the persons and groups — by id — that use them free, and whether the public may buy them.
  • const AudienceSettings({required this.revision, required this.freeWith, required this.publicPaid}) — The setting at [revision].
  • final int revision — The revision the website keeps; a write names the one it read, and a stale one is refused terms-conflict.
  • final List<String> freeWith — The ids of the persons and groups that use the offers free, each the design’s Uuid.
  • final bool publicPaid — Whether anyone else may buy the offers at their price.
• class PublicName — A name as anybody may read it (GET /v1/community/names/{username}): its id, its username and its kind, person or group — exactly those, as the website answers them.
  • const PublicName({required this.id, required this.username, required this.kind}) — The name [username], whose id is [id].
  • final String id
  • final String username
  • final String kind
• class Lending — The website’s lending, the supplier’s side and the requester’s: each method one operation of the design, answering its value or throwing [LendingRefused].
  • const Lending() — Creates a client without account or transport work.
  • static Lending get current — The installed client; [NoLending] by default.
  • static void install(Lending lending) — Installs [lending] without calling it.
  • static final published — The ids of this computer’s shared offers the website acknowledged as published, as the lending loop last heard it: set by the loop at each turn, emptied at sign-out and when the loop stops, and read by *Share my plugi…
  • Future<String> declare(String offerId, Map<String, Object?> declaration) — Declares the offer [offerId] with [declaration] (PUT /v1/lending/offers/{offerId}), answering the version the website hashed it to: the same for an equal declaration, another for a changed one.
  • Future<void> publish(String offerId, String version, bool published) — Publishes the offer [offerId] at [version], or withdraws it, as [published] says (PUT /v1/lending/offers/{offerId}/publication): a desired state, the last write winning.
  • Future<void> setAvailability(String state) — Sets this device’s availability: available, busy or unavailable (PUT /v1/lending/availability).
  • Future<List<LendingJobSummary>> inbox() — The inbox’s first page: this device’s requested and accepted jobs, oldest first, fifty a page (GET /v1/lending/jobs, no query); reading it refreshes this device’s presence.
  • Future<List<LentOffer>> offers() — The published offers this account may render on, discovery’s first page (GET /v1/lending/offers).
  • Future<List<LentOffer>> supplied() — Every version of every offer this account owns, published or not, on any device, every page (GET /v1/lending/offers?role=supplier, the bearer alone).
  • Future<LendingJob> prepare(String id, {required String offerId, required String version, required List<({String unit, String quantity})> quantities… — Prepares the job [id] on the offer [offerId] at [version] — [quantities] per unit, the opaque JSON [input], at the [expectedPriceCents] the person was shown (POST /v1/lending/jobs).
  • Future<LendingJob> job(String id) — The job [id] (GET /v1/lending/jobs/{id}).
  • Future<void> decide(String id, String decision, {String? code, Map<String, Object?>? result}) — accept, refuse, fail, complete or cancel on the job [id], with [code] for a refusal or a failure and the opaque [result] for complete, which publishes it (POST …/decision).
  • Future<AudienceSettings> audience() — This account’s audience (GET /v1/lending/settings); refused lending-unavailable where no client is installed.
  • Future<AudienceSettings> setAudience(AudienceSettings settings) — Writes the audience as [settings], own devices fixed, naming the revision read (PUT /v1/lending/settings), and answers what the website keeps now; a stale revision is terms-conflict.
• class NoLending — The client of a build that installed none: every operation is refused lending-unavailable, and nothing is sent.
  • const NoLending() — The inert client.

lib/src/lifecycle_hook.dart

• class LifecycleHook — The app’s lifecycle heard by an owner that can be disposed while an exit is being dispatched (§7).
  • LifecycleHook({required this.owner, this.onStateChange, this.onExitRequested}) — Hears the app for [owner], named in the log, until [dispose].
  • final String owner — Who holds the hook, as the log names it.
  • final void Function(AppLifecycleState state)? onStateChange — Told each change of the app’s lifecycle state.
  • final Future<AppExitResponse> Function()? onExitRequested — Asked when the app is asked to exit; no answer is [AppExitResponse.exit].
  • void dispose() — Stops hearing the app; a call after this is logged and answered as nothing.

lib/src/localization_provider.dart

• variable final localizationsProvider — The strings in effect, for code that has no BuildContext (the tree builder runs inside a provider).
• variable const shownLocales — The languages the app shows: English alone while FilmOpen is in development (§10).
• function Locale resolveSupportedLocale(Locale locale) — The shown locale that best matches [locale]: same language, else English ([shownLocales]).
• function bool keepsLanguage(String languageCode) — Whether the app keeps strings for [languageCode], shown or not (§10).

lib/src/media_availability.dart

• enum EnsureOutcome — How [MediaAvailability.ensure] ended (§6.14).
  • values: local, fetched, failed
• class MediaAvailability — The application’s [MediaFetch], over the sync’s available media: a read of a remote-only file downloads it through the sync’s own fetch job and waits for that job (§6.14, media on demand).
  • MediaAvailability(this._service) — Hears [service]’s availability from now on; starts nothing else.
  • Set<String> remoteIn(String projectKey) — The film’s available media now, as project-relative paths.
  • Future<({EnsureOutcome outcome, String? code})> ensure(ProjectSource source, String path, {String reason = 'read'}) — Makes the project-relative media [path] of the film [source] holds local, deciding from that film alone (§6.14): in the source → at once; else available at the sync → through [SyncService.fetchNow], following that job…
  • Future<void> close() — Stops hearing the sync.
• function int remoteMediaIn(String projectKey) — How many media files of the film [projectKey] are available at the sync, by the installed seam.
• function Future<String?> ensureFilmMedia(ProjectSource source) — Makes every available media file of the film [source] holds local in turn, as the copy to a folder needs them all (§6.14); answers the first failure’s code, or null.
• typedef typedef SceneMediaEnd — How a scene’s media fetch ended: the scene’s [timeline] built from them, or the first [missing] file and its [code].
• variable final sceneMediaProvider — The scenes’ [SceneMedia]: what fetches a scene’s remote media before it plays or is exported (§6.14).
• class SceneMedia — A scene’s media made local together before it plays or is exported, then its timeline built from them (§6.14).
  • SceneMedia(this._ref) — Reads the open project, its media store and the scenes’ timelines through [_ref].
  • Future<SceneMediaEnd> ready(String stem, {required String reason, void Function(int done, int total)? onProgress}) — Fetches the remote media of the scene [stem] together, then answers its timeline built again from them.

lib/src/media_client.dart

• typedef typedef MediaObject — An object stored for a day under the account: its key, the URL anyone holding it may read, and when that ends.
• class MediaRefused — A refusal of the media client, by its code alone — with the website’s status where one answered.
  • const MediaRefused(this.code, {this.status}) — A refusal under [code].
  • final String code — The refusal’s code, for the consumer to word; never a server’s words.
  • final int? status — The HTTP status that carried the refusal, null where nothing was sent or nothing answered.
• class MediaClient — The seam through which bytes become a URL a provider or another device can fetch (§6.6).
  • const MediaClient() — Creates a client without account or transport work.
  • static MediaClient get current — The installed client; [NoMediaClient] by default.
  • static void install(MediaClient client) — Installs [client] without calling it.
  • Future<MediaObject> upload(List<int> bytes, String contentType) — Stores [bytes] of [contentType] and answers where they can be read; throws [MediaRefused] with a code.
• class NoMediaClient — The client of a build that installed none: every upload is refused media-not-configured, and nothing is sent.
  • const NoMediaClient() — The inert client.

lib/src/media_entry_actions.dart

• class MediaEntryActionContext — The captured media entry’s place and write access, without importing a consumer widget.
  • const MediaEntryActionContext({ required this.projectKey, required this.stem, required this.canWrite, required this.canRunPlugins, }) — Captures the entry’s project and entity identity with its current write access.
  • final String projectKey — The film containing the clicked entry.
  • final String stem — The entity version whose media menu was opened.
  • final bool canWrite — Whether that version is writable; read actions may still apply when false.
  • final bool canRunPlugins — Whether plugins may run here, independent of ownership; selection revalidates captured access before execution.
• enum MediaEntryActionReason — A local entry or access condition that a menu translates without inventing a provider error.
  • values: readOnly, pluginsNotAllowed, unsupportedMedia, missingEntry, busy, stale, analyzerNotInstalled, analyzerDisabled, analyzerNotRunnable, analyzerNoInterface, analyzerParentDisabled, analyzerNoGrant, analyzerNoKey, analyzerStoreUnavailable, analyzerChecking, analyzerDraftUnsaved, noHandle, compPosting
• class MediaEntryActionAvailability — Whether a per-entry action can run, with a typed refusal rather than prose.
  • const MediaEntryActionAvailability() — Creates a typed availability answer.
• class MediaEntryActionAvailable — The clicked media entry’s action is available.
  • const MediaEntryActionAvailable() — Creates an available answer without starting the action.
• class MediaEntryActionUnavailable — The action remains discoverable but is unavailable for a typed reason.
  • const MediaEntryActionUnavailable(this.reason) — Captures the reason the shared menu later translates.
  • final MediaEntryActionReason reason — The localized consumer’s reason code.
• class MediaEntryProviderUnavailable — An entry action blocked by a provider route, retaining the provider’s specific reason.
  • const MediaEntryProviderUnavailable(this.reason) — Captures the route refusal without conflating it with local media or access conditions.
  • final ProviderUnavailableReason reason — The provider condition translated by the menu consumer.
• class MediaEntryAction — An injected media-entry menu action, mirroring the insertion action’s presentation doors.
  • const MediaEntryAction() — Creates an action without invoking its consumer.
  • String get id — The last segment of this item’s semantics identifier.
  • String label(AppLocalizations l10n) — The menu label from the application’s localization catalogue.
  • IconData get icon — The icon retained where the label does not fit.
  • bool appliesTo(MediaEntry entry, MediaEntryActionContext context) — Whether the action belongs on this entry, independent of write access alone.
  • bool get gatedByEntityAccess — Whether the menu refuses the action where the version allows neither writing nor plug-ins; false for an action that writes the viewer’s own record rather than the version, and decides its access itself.
  • MediaEntryActionAvailability availableFor(MediaEntry entry, MediaEntryActionContext context) — Whether the action can run now, without performing the operation.
  • Future<void> onSelected(MediaEntry entry, MediaEntryActionContext context) — Runs only after selection, revalidating entry identity and permissions captured by its menu.
• class MediaEntryActions — The ordered per-entry action registry, empty and silent until something registers.
  • static List<MediaEntryAction> get all — An immutable ordered snapshot for the shared menu.
  • static Stream<void> get changes — Signals after registration or removal, without invoking any action.
  • static void Function() register(MediaEntryAction action) — Registers one occurrence and returns an idempotent remover for exactly that occurrence.

lib/src/media_provider.dart

• variable final mediaStoreProvider — The store of the open project’s media folder; null while no project is open.

lib/src/microphone_ownership.dart

• class MicrophoneOwner — A named capture attempt with fresh identity, even when a controller records again.
  • MicrophoneOwner(this.name) — Creates a new attempt; never reuse this object for a subsequent capture.
  • final String name — The caller’s nonsecret owner identifier, localized by the eventual consumer.
• class MicrophoneAcquisition — The synchronous acquisition result, with no microphone opened by the arbiter.
  • const MicrophoneAcquisition() — Creates a grant or occupied answer.
• class MicrophoneGranted — Ownership granted to this capture attempt without starting capture.
  • const MicrophoneGranted(this.owner) — Records the exact attempt allowed to release this ownership.
  • final MicrophoneOwner owner — The attempt that now holds the microphone.
• class MicrophoneOccupied — An occupied microphone, naming the capture attempt that already owns it.
  • const MicrophoneOccupied(this.owner) — Records the owner that the requester must not displace.
  • final MicrophoneOwner owner — The existing owner, which remains unchanged.
• class MicrophoneOwnership — The one ownership arbiter above audio capture, independent of AudioSource.
  • const MicrophoneOwnership() — Creates an arbiter without accessing an audio platform.
  • static MicrophoneOwnership get current — The installed arbiter, the single pure in-memory arbiter by default.
  • static void install(MicrophoneOwnership arbiter) — Installs a different arbiter only after the current owner has completed cleanup and released.
  • static Stream<void> get installations — Signals replacement to already observing consumers.
  • MicrophoneOwner? get owner — The current owner, or no capture attempt holding ownership.
  • Stream<MicrophoneOwner?> get owners — Ordered ownership transitions, with a getter supplying the initial snapshot.
  • MicrophoneAcquisition acquire(MicrophoneOwner owner) — Grants only an unoccupied microphone and otherwise names the current owner.
  • void release(MicrophoneOwner owner) — Releases only the exact owning attempt after its audio cleanup has completed.
• class InMemoryMicrophoneOwnership — A pure ownership arbiter that never starts capture, a channel or preferences.
  • InMemoryMicrophoneOwnership() — Creates an unoccupied arbiter without listeners or platform work.
  • void dispose() — Closes an unoccupied isolated arbiter’s observers; occupied disposal refuses before changing its state.

lib/src/native_conversation.dart

• variable const Duration conversationFinishDrain — The maximum caption drain after capture stops, while admitted sockets remain open.
• class ConversationSupport — Whether the installed native service supports conversation, with a typed refusal.
  • const ConversationSupport.available() — Declares implemented native conversation support without opening a session.
  • const ConversationSupport.unavailable(this.reason) — Declares an unavailable route without silently changing provider.
  • final bool available — Whether the implementation supports this native capability.
  • final ProviderUnavailableReason? reason — Why the capability is unavailable, when it is.
• class ConversationBinding — The immutable provider, voice model, format and funding choice captured by open.
  • const ConversationBinding({ required this.providerTag, required this.model, required this.voice, required this.audioFormat, required this.funding, }) — Captures the selected native tuple without connecting or acquiring the microphone.
  • final String providerTag — The selected speech provider, never an inferred fallback.
  • final String model — The compatible conversation model, independent of a text-model choice.
  • final String voice — The selected compatible voice.
  • final String audioFormat — The selected provider-supported audio format.
  • final FundingResult funding — The resolved route captured for this session, unavailable until genuinely funded.
• enum ConversationState — The native session’s visible state, including unavailable and bounded finishing.
  • values: unavailable, idle, starting, active, muted, finishing, ended, closed
• enum ConversationSpeaker — The speaker of a caption event.
  • values: user, assistant
• class ConversationCaption — One caption revision with a stable turn identity, distinct from final committed text.
  • const ConversationCaption({required this.turnId, required this.speaker, required this.text, required this.isFinal}) — Captures provider caption data without logging or persisting it.
  • final String turnId — The turn whose partial text this revision replaces.
  • final ConversationSpeaker speaker — The speaker whose caption this is.
  • final String text — The visible transcript text, excluded from ordinary and debug logs.
  • final bool isFinal — Whether this event completes the turn’s caption.
• class ConversationUsage — Provider-reported usage units, preserved without implying a monetary charge.
  • ConversationUsage({required this.chain, required Map<String, Object?> units}) — Copies and freezes the provider’s unit breakdown without estimating billing.
  • final String chain — The host correlation for the conversation or caption usage chain.
  • final Map<String, Object?> units — The reported units as received, never a credit settlement or microphone-time charge.
• enum TranscriptCompleteness — Whether captions are complete, explicitly incomplete or unavailable.
  • values: complete, incomplete, unavailable
• class ConversationTranscript — A frozen visible transcript retained after End, Close or Finish.
  • ConversationTranscript({List<ConversationCaption> captions = const [], required this.completeness}) — Freezes the caption list and explicitly retains its completeness.
  • final List<ConversationCaption> captions — The admitted captions retained for visible review, never automatic project writing.
  • final TranscriptCompleteness completeness — Whether a consumer must ask before using a partial transcript.
• class ConversationSnapshot — A native session snapshot, observable without starting a transport.
  • const ConversationSnapshot({required this.state, required this.transcript}) — Captures visible state and retained transcript.
  • final ConversationState state — The session’s current visible state.
  • final ConversationTranscript transcript — The transcript that remains after immediate teardown or bounded finish.
• enum ConversationOperationCode — A typed native operation result, never a thrown unsupported sentence.
  • values: completed, unsupported, notReady, unfunded, closed, cancelled
• class ConversationOperationResult — The result of starting, muting, interrupting or ending a session.
  • const ConversationOperationResult(this.code, {this.reason}) — Captures a fixed outcome and optional typed refusal.
  • final ConversationOperationCode code — What the operation achieved or why it could not run.
  • final ProviderUnavailableReason? reason — The route’s typed unavailable reason, where applicable.
• enum ConversationFinishReason — Why a finish returned its frozen transcript.
  • values: finished, timedOut, ended, closed, unsupported
• class ConversationFinished — A finish outcome that preserves an explicitly complete or partial frozen transcript.
  • const ConversationFinished({required this.transcript, required this.reason}) — Captures the retained transcript and the terminal drain outcome.
  • final ConversationTranscript transcript — The transcript frozen before any separate finalizer is invoked.
  • final ConversationFinishReason reason — Whether drain completed, timed out, was interrupted or was unsupported.
• class ConversationSession — A bound native conversation whose resource ownership begins only on explicit Start.
  • const ConversationSession() — Creates a session interface without connecting a transport.
  • ConversationBinding get binding — The immutable choice captured by open, retained through Finish and teardown.
  • ConversationSnapshot get snapshot — The current state and transcript without a request or capture side effect.
  • Stream<void> get changes — Signals after the visible session snapshot changes.
  • Stream<ConversationCaption> get captions — Admitted caption revisions keyed by turn, still delivered during the finish drain.
  • Stream<ConversationUsage> get usage — Provider-reported units, still delivered during drain without inferring billing.
  • Future<ConversationOperationResult> start() — Admits only a ready, funded session after explicit action, acquiring native resources then.
  • Future<ConversationOperationResult> mute(bool muted) — Changes capture muting without retargeting the frozen session binding.
  • Future<ConversationOperationResult> interrupt() — Interrupts spoken output through the bound native provider protocol.
  • Future<ConversationOperationResult> end() — Immediately tears down all resources and retains the transcript without finalizing or writing.
  • Future<ConversationFinished> finish() — Stops capture, commits pending audio and stops spoken output before draining admitted caption events.
  • Future<ConversationOperationResult> close() — Immediately tears down resources, including while Finish drains, and retains the visible transcript.
• class NativeConversation — The host-installed native conversation door, unsupported until an implementation is installed.
  • const NativeConversation() — Creates a service without accessing audio, credentials or sockets.
  • static NativeConversation get current — The installed native service, unsupported by default.
  • static void install(NativeConversation service) — Installs an implementation without opening or starting a session.
  • static Stream<void> get installations — Signals replacement to consumers that already read support.
  • ConversationSupport get support — The implemented capability’s truthful support state.
  • Stream<void> get changes — Signals after support changes, without admitting a conversation.
  • ConversationSession open(ConversationBinding binding) — Captures the frozen choice only, acquiring no microphone and connecting no socket.
• class NoNativeConversation — The inert native service, answering unsupported without throwing a sentence.
  • const NoNativeConversation() — Creates the unavailable service.
• class UnavailableConversationSession — An inert bound session retaining an unavailable empty transcript and opening nothing.
  • UnavailableConversationSession(this.binding) — Captures the chosen binding without native work.

lib/src/page_access.dart

• enum GuardNotice — A red line a page shows in development mode.
  • values: otherAuthor, notDirector, libraryFile, noHandle, sessionCopy, readOnlyFolder, libraryReadOnly
• enum ChildrenLock — Why a version’s children may not be changed.
  • values: noHandle, readOnly, notYours
• class PageAccess
  • const PageAccess({ required this.editable, required this.canSetOfficial, required this.canPick, required this.choosesNothing, required this.canLabe…
  • factory PageAccess.of(FilmProject project, Entity entity, Author? viewer, Guards guards)
  • final bool editable — The form writes: the viewer’s own version, or — in development mode — anybody’s, the shared library’s included where the library can be written.
  • final bool canSetOfficial — The star can be pressed: never on a discarded version, which a pointer would name as none (§6.1).
  • final bool canPick — The check can choose the version in use: never on a plug-in (§6.11), nor on a discarded version (§6.1).
  • final bool choosesNothing — Neither the check nor the star chooses anything here: a plug-in, whose installed version runs whatever the film (§6.11).
  • final bool canLabel — The version label can be edited.
  • final bool canRunPlugins — Plugins… may run a plug-in on the file shown: from anybody’s version, since the run never writes over it.
  • final List<GuardNotice> notices — The red lines the page shows, in this order.
  • final ChildrenLock? childrenLock — Why this version’s children may not be changed.
  • bool get canEditChildren — Whether a folder or scene may be added to, removed from or moved in this version’s children.
  • static bool canCreateVersions(FilmProject project, Author? viewer) — Whether the viewer may make new versions in [project] (§8.2).

lib/src/plugin_readiness.dart

• function String? pluginWords(Object? value, {int most = 300}) — A plug-in’s own words, cleaned for a card or a page (§6.11): at most [most] characters, or null for none.
• enum PluginSwitchNotSaved — Which switch of the person’s could not be saved.
  • values: off, on
• enum PluginLifecyclePhase — Where a plug-in’s own work on being turned on or off, or a Check, stands — apart from its switch, which says whether it is on, and from what it last said of itself (§6.11).
  • values: idle, enabling, disabling, checking
• class PluginStatusDetails — The measured facts of a plug-in’s status that the app shows with its own labels and units (the definition’s Status.details); each one absent is unknown, never zero.
  • const PluginStatusDetails({this.serviceVersion, this.gpu, this.gpuMemoryBytes, this.memoryBytes}) — The four facts the app reads, each where the plug-in gave it.
  • factory PluginStatusDetails.fromJson(Object? details) — The four facts copied out of a status’s details, and nothing else of the plug-in’s own.
  • final String? serviceVersion — The version of the service it reached, as the service reports it.
  • final String? gpu — The graphics card the service runs on, as the service names it.
  • final int? gpuMemoryBytes — That card’s memory, in bytes.
  • final int? memoryBytes — The memory of the computer the service runs on, in bytes.
  • bool get isEmpty — Whether the plug-in gave none of the four, so that nothing is drawn for them.
• class PluginStatusFact — What a plug-in last said of whether it can work: one of the four states, its own words and the facts it measured.
  • const PluginStatusFact(this.state, {this.message, this.details = const PluginStatusDetails()}) — A state, with the plug-in’s words and facts where it gave them.
  • final PluginStatusState state — Which of the four states it said: ready, unconfigured, unavailable or degraded.
  • final String? message — The plug-in’s own words, in the language they were asked in; null where it gave none, or where the app’s language changed since, so that one line is never in two languages.
  • final PluginStatusDetails details — What it measured, of the four facts the app shows; each one it did not give unknown.
  • PluginStatusFact withoutMessage() — This fact without the plug-in’s words, for a language other than the one it was asked in.
• enum PluginLifecycleProblemKind — What became of the last operation of a plug-in’s lifecycle, or of its last Check, where it did not succeed.
  • values: activationFailed, activationTimedOut, activationHung, notPublished, checkFailed, cleanupFailed, cleanupTimedOut, cleanupSkipped
• class PluginLifecycleProblem — Why the last operation of a plug-in’s lifecycle, or its last Check, did not succeed: its kind, a code that is safe to show and to log, and the plug-in’s own words where it gave some.
  • const PluginLifecycleProblem(this.kind, {this.code, this.reason, this.path, this.message}) — A problem of [kind], with what is known of it.
  • final PluginLifecycleProblemKind kind — What did not succeed, and so which sentence says it.
  • final String? code — The call’s failure code (failed, limit, refused, badResult, …), or the plug-in’s own problem code where it is a token; never prose.
  • final String? reason — The code’s reason, where it has one (wall, no-server).
  • final String? path — Where an answer failed the definition (status.state), for badResult.
  • final String? message — The plug-in’s own words, in the language they were asked in; null after the app’s language changed.
  • bool get retryable — Whether Try again is offered: for an activation or a check that did not succeed of a plug-in still on — never for a clean-up, nor for one that hung or did not come on, which is off and which its switch, or Allow,…
  • bool get isCleanup — Whether it is about the plug-in being turned off.
  • PluginLifecycleProblem withoutMessage() — This problem without the plug-in’s words, for a language other than the one they were in.
• class PluginReadiness — What the app knows now of whether a plug-in can work, the one record its card and its page both draw (§6.11).
  • const PluginReadiness({ required this.stem, this.phase = PluginLifecyclePhase.idle, this.declaresLifecycle = false, this.fact, this.saysNothing = f… — What is known of [stem].
  • final String stem — The plug-in this is known of.
  • final PluginLifecyclePhase phase — Where its own work stands: idle, being turned on or off, or checked.
  • final bool declaresLifecycle — Whether its manifest declares the lifecycle interface, so that turning it on or off asks its code.
  • final PluginStatusFact? fact — What it last said; null where nothing is known — the app started since, it was turned on with nothing to ask, or what it said no longer holds because its code, its grants, its settings or its keys changed.
  • final bool saysNothing — It was asked, and its code has no status: Check says so, and its other functions still run.
  • final PluginLifecycleProblem? problem — Why the last operation did not succeed; null where it did, or nothing ran.
  • final PluginSwitchNotSaved? switchNotSaved — The person’s switch that could not be saved, where one was not: an Off, off for this session and perhaps on again at the next start; or an On, which did not come on.
  • bool get isBusy — Whether a phase is under way.

lib/src/plugin_runtime.dart

• class PluginRoleBase — What a plug-in’s runtime is, by the job a caller has: four roles over PluginRoleBase, which [PluginRuntime] implements all four of.
  • const PluginRoleBase()
  • bool get isAvailable — Whether plug-ins can run here at all (false on the web).
  • Listenable get changes — Tells listeners the plug-ins, their settings or their grants changed.
• class PluginCatalogueView — What is installed and what it says of itself.
  • const PluginCatalogueView()
  • static PluginCatalogueView get current — The runtime in use, as this role and no more.
  • int get apiRevision — What this build has of the plug-in interface.
  • List<PluginSummary> get plugins — Every plug-in found in the library and the development folder.
  • Future<List<ScriptWriter>> scriptWriters() — The enabled scriptwriting plug-ins with their checked workflow JSON or its refusal.
  • Future<Uint8List> pluginFile(String tag, String path) — A file under assets/ of the enabled plug-in [tag], as bytes.
  • String? pluginString(String tag, String key, {String? locale, Map<String, Object?> args = const {}}) — An English-backed string of the enabled plug-in [tag], its placeholders filled.
  • List<PluginKeyOwner> get keyOwners — The key slots a plug-in’s page draws, a section per enabled plug-in that declares any.
  • List<PluginSection> sectionsFor(EntityType type) — The cards a page of [type] draws after its own sections.
  • List<PluginProvider> providers(String hook) — The enabled plug-ins providing [hook], for Settings → Plugins’ preferred providers and a page’s Plugins menu.
  • PluginReadiness readiness(String stem) — What is known now of whether [stem] can work (§6.11), the one record its card and its page draw: the phase under way, what it last said — copied, and dropped once its code, grants, settings or keys changed — and w…
• class PluginFileRefused — A package file refused with a safe code alone, never its path.
  • const PluginFileRefused(this.code)
  • final String code — notInstalled, notEnabled, path or notAvailable.
• class PluginSettingsControl — What the person may change: a plug-in on or off, consent given, a key granted, a setting typed, a preferred provider chosen, a plug-in installed.
  • const PluginSettingsControl()
  • static PluginSettingsControl get current — The runtime in use, as this role and no more.
  • Future<void> setEnabled(String stem, bool enabled)
  • List<SharedOffer> get sharedOffers — The offers this computer shares (§6.11, Lending), as the person fixed them: kept beside the enabled list, read by the lending loop at each turn.
  • Future<void> setSharedOffers(List<SharedOffer> offers) — Writes the whole list of shared offers, one writer at a time, and tells the listeners.
  • Map<String, String> get freeWithNames — The usernames this computer resolved for the ids of the account’s free list (§6.11, Lending), by id: the account keeps ids alone, so a chip reads its name from here.
  • Future<void> setFreeWithNames(Map<String, String> names) — Writes the whole map of resolved names.
  • Future<void> allow(String stem) — The person’s Allow on the consent screen.
  • Future<void> retry(String stem) — Try again after [stem]’s turning on, or its Check, did not succeed: the same operation once more, told it is a retry.
  • Future<void> setGrant(String stem, String keyId, bool granted)
  • Future<void> setMachineSetting(String tag, String key, Object? value) — A machine-scoped setting’s value; null removes it.
  • Map<String, Map<String, Object?>>? get machineSettingsSnapshot — A private deep copy for binding new work, or null while the current registry/settings load is incomplete.
  • Future<void> setPreferred(String kind, String tag) — The preferred plug-in for text or media, consulted only where more than one plug-in serves the model asked for.
  • Future<void> setRoute(String tag, Map<String, Object?>? candidate) — Saves a text route and prefers its plug-in; null restores Automatic while retaining that preference.
  • Future<PluginInstallOutcome> installArchive(Uint8List bytes) — Install from file…: a zip, unpacked into the library.
  • String? get devFolder — The folder of plug-ins being written on this computer, whose sub-folders are read beside the library’s and found first (§3.6); null where the person has named none and the environment names none either.
  • Future<void> setDevFolder(String? path) — Names the development folder, or clears it with null.
• typedef typedef PromptWriter — A prompt writer offered for a prompt kind, with its model, quote and completion origin.
• typedef typedef WriterToken — One media token a prompt writer is handed: as it is written in a prompt, and the person’s name for it.
• typedef typedef ScriptWriter — An enabled scriptwriting plug-in, its translated label and checked workflow or refusal.
• typedef typedef DecidedModel — A step’s decided text model and rate, with its selection reason or unavailability.
• class PluginStepRun — A workflow step’s outcome, decided model, answer text and ledger spend in USD.
  • const PluginStepRun({required this.outcome, this.model, this.text, this.spent, this.spentKnown = false, this.ceilingWhy, this.ceilingWorstCase}) — Keeps the outcome and any model, text and spend known for the step.
  • final PluginCallOutcome outcome — The call’s outcome, with the plug-in’s failure words preserved.
  • final DecidedModel? model — The model decided before the call, absent when admission failed first.
  • final String? text — The plug-in’s answer text where it returned a string.
  • final String? spent — The sum of the ledger’s USD costs as a decimal string.
  • final bool spentKnown — Whether every chain has a known USD cost, true for no chains.
  • final String? ceilingWhy — Why the ceiling refused the step’s first refused completion — over, rate or outputLimit —; null for none.
  • final String? ceilingWorstCase — That completion’s worst case in USD as a decimal string; null where its rate or output limit is unknown.
• class PluginInvocation — What may be run: the calls a page, a card or the app itself makes.
  • const PluginInvocation()
  • static PluginInvocation get current — The runtime in use, as this role and no more.
  • Future<PluginCallOutcome> runAction(String stem, String action, {PluginCallControl? control}) — Runs an action of the plug-in’s page.
  • Future<PluginCallOutcome> signInKey(String keyId, {PluginCallControl? control}) — Signs in directly to an enabled plug-in’s declared OAuth slot, without running its code.
  • Future<PluginCallOutcome> signOutKey(String keyId, {PluginCallControl? control}) — Revokes and clears an enabled plug-in’s declared OAuth slot, without running its code.
  • Future<PluginCheckResult> checkStatus(String stem, {PluginCallControl? control}) — Check: asks the plug-in whether it can do its work now.
  • Future<PluginCallOutcome> runEntityHook(String tag, String hook, List<Entity> selection, {PluginCallControl? control}) — Runs an entity hook on [selection], each entity as the film’s view holds it when the call is admitted to run (§6.11).
  • Future<PluginKeyCheck?> verifyKey(String keyId, Map<String, String> values) — Checks a key the person just typed with the plug-in that provides verifyKey for its platform, the owning plug-in first: the candidate is usable through ctx.http for that one call and is never stored here.
  • Future<PluginCallOutcome> call(String hook, Map<String, Object?> args, {Entity? source, PluginCallControl? control}) — Calls a platform hook through the plug-in chosen for the model asked for: render with {model, prompt, inputs, params} for [source] — the one call Generate makes (the architecture’s test).
  • Future<PluginCallOutcome> defaultModels({List<String>? kinds, List<String>? stages, PluginCallControl? control}) — The selected model picker’s defaults for [kinds] and [stages], all where null.
  • List<PromptWriter> promptWriters({required String target, String? model}) — The enabled plug-ins’ writers of the prompt kind [target] — those for [model] alone left out where another model is given — in the order offered: fo-prompts‘s first, then the other plug-ins’ by tag, each in its mani…
  • Future<DecidedModel?> decideStep(String tag, String stepId) — Decides a declared step’s model and rate without running it, or null for no such step.
  • Future<PluginStepRun> runOffer(String tag, String stepId, Map<String, Object?> args, {PluginCallControl? control, double? ceiling}) — Runs a checked workflow step with its declared model and wall and the caller’s filled arguments.
  • Future<PluginCallOutcome> buildPrompt({required String target, required Entity source, String? model, String? plugin, String? writer, String? block… — A prompt for [target] from the supplied draft [source], written by [plugin]’s writer [writer] — the pair a prompt is saved with —, by [plugin]’s first where no [writer] is named, else by the first of [promptWriters];…
  • Future<PluginCallOutcome> callCapability(String tag, String function, Map<String, Object?> args, { required Entity source, PluginCallControl? contr… — Calls [function] of a capability on the enabled plug-in [tag], which implements its interface, for [source].
  • Future<PluginCallOutcome> callServer(String tag, String function, Map<String, Object?> args, {PluginCallControl? control}) — Calls [function] of the server-provider interface on the enabled server provider [tag].
• class PluginDevBench — The plug-in developer page’s own road (Software Specification §9.4a).
  • const PluginDevBench()
  • static PluginDevBench get current — The runtime in use, as this role and no more.
  • Future<PluginDevPlugin?> devOpen(String stem) — [stem] as the developer page shows it, its files read from disk again.
  • Future<PluginDevRun> devRun(String stem, String function, Object? args, { List<Entity> selection, Entity? source, PluginCallControl? control, void… — Runs [function] of [stem] from its files as they are on disk, with no consent asked and every key its manifest names granted for the run.
  • Future<void> devClose(String stem) — Forgets what the page wrote for [stem]: its last-run.json.
  • List<PluginDevFolderProblem> get devFolderProblems — The development folder’s plug-in folders that could not be read, each with its path.
• class PluginRuntime — The seam plug-ins attach to: what the app’s pages, Settings and the agent layer may ask of the plug-in runtime, as an interface with a no-op default.
  • const PluginRuntime()
  • static PluginRuntime current — The runtime in use.
  • static void install(PluginRuntime runtime) — Installs [runtime]; called by an entrypoint before the app runs.
  • void attach(ProviderContainer container) — Called once by main with the container every provider lives in.
• enum PluginDevMode — How the developer page calls a function.
  • values: app, typed, console
• class PluginDevFolderProblem — A plug-in folder of the development folder that could not be read.
  • const PluginDevFolderProblem({required this.tag, required this.path})
  • final String tag
  • final String path — Where it is on this computer, for a person to go and look.
• enum PluginOrigin — Where a plug-in was found.
  • values: stock, library, development
• enum PluginFieldType — A field a plug-in declares, as a page draws it.
  • values: string, text, number, boolean, choice, model, server, program
• class PluginField — One field: its key, its words in the app’s language, and its rules.
  • const PluginField({ required this.key, required this.type, required this.label, this.help, this.choices = const [], this.min, this.max, this.defaul…
  • final String key
  • final PluginFieldType type
  • final String label
  • final String? help
  • final num? min
  • final num? max
  • final Object? defaultValue
  • final String? category — For a model: the catalogue category and, optionally, platform.
  • final String? platform
  • final Object? value — The value stored, for a machine setting on the plug-in’s page; a page’s own draft holds the others.
  • final String? foundPath — The executable found on PATH, awaiting the person’s acceptance.
  • final bool notExecutable — Whether the stored program path is no longer an executable file.
• class PluginSection — A plug-in’s card on an entity’s page or the project’s.
  • const PluginSection({required this.tag, required this.title, required this.fields})
  • final String tag
  • final String title
  • final List<PluginField> fields
• class PluginGrant — A key a plug-in asks to use, and whether the person granted it.
  • const PluginGrant({ required this.keyId, required this.ownerName, required this.slot, required this.granted, required this.stored, this.platformNam…
  • final String keyId
  • final String ownerName
  • final String? platformName — The name of the platform the key is for (fal.ai), where one is known: what consent says the key spends on.
  • final String slot — The slot in its owner’s words (OpenRouter), else its name.
  • final bool granted
  • final bool stored — Whether a key is saved for it, as Provider keys records it — never the key.
• class PluginAction — A button on a plug-in’s page.
  • const PluginAction({required this.id, required this.label})
  • final String id
  • final String label
• class PluginProblemInfo — A problem found in a plug-in’s files, as a code and the path it concerns.
  • const PluginProblemInfo({required this.code, required this.path, this.field, this.args = const {}})
  • final String code
  • final String path
  • final String? field
  • final Map<String, Object?> args
• class PluginSummary — One plug-in as Settings → Plugins lists it.
  • const PluginSummary({ required this.stem, required this.tag, required this.author, required this.version, required this.name, required this.origin,…
  • final Map<String, Object?> route — The host-selected text funding route; absent where no text platform is known.
  • final List<Map<String, Object?>> routes — Every route the plug-in can run on, in the owner’s order — this computer, program, sign-in, key, credit — each {platform, funding, slot\|program\|key, text, image, ready, why} as the host holds it (§6.11).
  • final String stem
  • final String tag
  • final String author
  • final int version
  • final String name
  • final String? description
  • final PluginOrigin origin
  • final bool enabled
  • final bool needsConsent — Off until the person allows it, or off again because its files changed.
  • final bool runnable — False when the host cannot run it: another api, no code file.
  • final List<String> ownKeys — The key slots it declares, by id.
  • final List<String> ownKeyNames — The same slots in the plug-in’s own words — its manifest’s label, else the platform’s name — in the order of [ownKeys], for consent, which is shown before the plug-in is on and so before Provider keys lists it.
  • final List<PluginGrant> grants
  • final List<String> hosts — Hosts reached without a key.
  • final List<PluginServer> servers — The server settings it declares.
  • final List<String> programs — The program setting labels that consent names, in manifest order.
  • final bool usesProcess — Whether the plug-in asks to run programs on this computer.
  • final String? kind — What sort of plug-in it says it is: platform, model or tool, or another token as written.
  • final List<PluginInterface> interfaces — What it implements (§14.4), each with its platform and its models.
  • final List<String> models — The catalogue entries it speaks for, from every interface it implements.
  • final List<String> unknownModels — Those of [models] the catalogue does not define: reported on its page, and the plug-in still runs.
  • final List<PluginOffer> offers — The functions it offers other plug-ins, each in its own words.
  • final List<PluginCalls> calls — The functions of other plug-ins it calls, grouped by the plug-in called and said in that plug-in’s words.
  • final List<String> dependencies — The plug-in tags its manifest’s x.dependencies names: the Plugins page draws it under them, and nothing else reads them — a call keeps its own guards.
  • final bool usesAi — capabilities.ai: it asks the preferred text model (ctx.ai.complete).
  • final bool usesUpload — capabilities.upload: it would send the film’s media to its platform or its server.
  • final int? minRevision — The least revision of the contract it needs (§14.4), where its manifest says one.
  • final List<String> applies — Entity type prefixes.
  • final List<String> hooks — Entity hooks and platform hooks, by name.
  • final List<PluginField> machineFields
  • final List<PluginAction> actions
  • final List<PluginProblemInfo> problems
  • final int linesNotWritten — How many ctx.log lines of this plug-in were a sentence rather than an event name, and so went to no file.
  • final String? readme
  • final String? docs — The manifest’s validated guide path below /docs/, on this build’s documentation site.
  • final bool keysSaved — Whether a declared or granted copied key is saved on its text platform, or any platform for another interface.
• class PluginDevPlugin — A plug-in as the developer page shows it.
  • const PluginDevPlugin({ required this.summary, required this.functions, required this.problems, required this.isStockCopy, required this.lastRunPat…
  • final PluginSummary summary — The plug-in as every other screen sees it: its name, its origin, its machine settings, what it asks for.
  • final List<PluginDevFunction> functions — What it exposes, in the order the page offers them.
  • final List<PluginProblemInfo> problems — Every problem its files have, by the file it concerns.
  • final bool isStockCopy — Its files are a stock plug-in’s installed copy, which the app replaces when it starts.
  • final String lastRunPath — Where the last run is written, and the developer’s own log: paths a person opens and an agent reads.
  • final String logPath
• class PluginDevFunction — One function the developer page offers to call.
  • const PluginDevFunction({required this.name, required this.label, required this.kind, this.example})
  • final String name — The function of the plug-in’s object.
  • final String label — What to show in the pull-down: its words where it has any, else its name.
  • final String kind — action, hook, offer — or other, the name a person typed.
  • final Object? example — The arguments to fill the box with.
• class PluginDevRun — One run made from the developer page.
  • const PluginDevRun({ required this.outcome, required this.elapsed, required this.lines, required this.lastRunPath, this.mode = PluginDevMode.app, t…
  • final PluginCallOutcome outcome
  • final Duration elapsed
  • final PluginDevMode mode — How it was called, and what the function was called with.
  • final Object? request
  • final List<PluginDevLine> lines — Every ctx.log line of the call and a row per door it used, in order.
  • final String lastRunPath — Where this run was written, for a person to open and an agent to read.
• class PluginDevLine — One line of the developer page’s log: a ctx.log the code made, or a door it used.
  • const PluginDevLine({ required this.at, required this.kind, required this.message, this.data, this.detail, this.milliseconds, this.by, })
  • final int at — Milliseconds since the run began, so a reader sees what took the time.
  • final String kind — The line holds what crossed into JavaScript: log for a line the code wrote, else the door’s own name (http, call, storage.get, project.script, …).
  • final String message — What the code said, or what the door was asked for.
  • final String? data — The JSON the code passed, or the door’s answer, cut at 64 KB with a mark.
  • final String? detail — A door’s own summary: a status, a size, a refusal’s reason.
  • final String? by — The tag of the plug-in that made this line, where it is not the one the page ran.
  • final int? milliseconds — How long a door took, where it waited.
• class PluginOffer — One function a plug-in offers, in its own words.
  • const PluginOffer({required this.name, required this.label, this.help, this.example})
  • final String name
  • final String label — The offering plug-in’s words for it, in the app’s language.
  • final String? help
  • final Object? example — A value of the arguments it takes, for a reader and for the developer page’s argument box.
• class PluginCalls — The calls one plug-in declares on another, as consent lists them.
  • const PluginCalls({required this.tag, required this.name, required this.labels, this.installed = true, this.keyPlatforms = const []})
  • final String tag
  • final String name — The called plug-in’s name, or its tag where it is not installed.
  • final List<String> labels — What each called function does, in the words of the plug-in that owns it.
  • final bool installed — False where the plug-in called is not installed: the page then says so, and every call answers noProvider.
  • final List<String> keyPlatforms — The platforms, by their names, of the keys the called plug-in owns.
• class PluginServer — A server setting as consent names it.
  • const PluginServer({required this.key, required this.label, this.defaultAddress})
  • final String key
  • final String label — The setting’s words in the app’s language.
  • final String? defaultAddress — The address it starts with, which can only ever be this computer.
• class PluginKeySlot — One card of Provider keys.
  • const PluginKeySlot({required this.keyId, required this.slot, required this.platform, this.label, this.help, this.auth = 'key', this.account, this.…
  • final String keyId — <owner>:<slot>.
  • final String slot
  • final String platform
  • final String? label
  • final String? help
  • final String? planLabel — The owning platform OAuth block’s plan name, independent of the slot label.
  • final String auth — The manifest’s authentication kind, independent of the platform’s copied key.
  • final String? account — The signed-in label from this slot’s existing key record; never a credential read.
  • final DateTime? expiresAt — The signed-in credential expiry from the same key record.
  • String get storeName — The credential store’s name for it.
  • String get preferenceName — The preference that holds its state.
• class PluginKeyOwner — A section of Provider keys: an owner and its slots.
  • const PluginKeyOwner({required this.owner, required this.name, required this.slots, this.platforms = const {}})
  • final String owner — The plug-in’s tag.
  • final String name
  • final List<PluginKeySlot> slots
  • final Map<String, PlatformFile> platforms — The owner’s own platform files, by id, for its slots on a platform the catalogue does not define (§14.9): a key’s file is the catalogue’s or its owner’s, never another plug-in’s.
• class PluginInterface — One interface a plug-in implements (implements, §14.4), as a page lists it.
  • const PluginInterface({ required this.name, this.platform, this.platformName, this.models = const [], this.kinds = const [], this.takes = const [],…
  • final String name — render, text, platform, transform, …
  • final String? platform — The platform’s id, where the interface asks for one.
  • final String? platformName — The platform file’s name for it (fal), where one is known.
  • final List<String> models — The catalogue entries it speaks for; empty is any on that platform.
  • final List<String> kinds — What it describes, for reference-analysis: image, audio or both; empty for any other interface.
  • final List<String> takes — The file extensions of the media it takes, for reference-analysis, lowercase; empty where it names none, and then it takes any media of its kinds.
  • final Map<String, Object?> declared — The manifest’s declaration of the interface, as written (catalog, target, platform, …).
• class PluginProvider — A plug-in that provides a hook, and for which platform.
  • const PluginProvider({required this.tag, required this.name, required this.hook, this.platform, this.platformName, this.preferred = false})
  • final String tag
  • final String name
  • final String hook
  • final String? platform
  • final String? platformName — The platform file’s name for [platform] (OpenRouter), where one is known.
  • final bool preferred
• class PluginCallControl — Progress and cancellation of a running call, shared by the page that started it.
  • final progress
  • final partial — The running streamed call’s visible text, appended in order by the host and cleared only by the control’s owner.
  • final note — The running call’s one current note — a passing word of what the model is doing, set by ctx.note (§6.11a) — replaced by the next, empty when there is none; never part of [partial] or of any message.
  • int call — The model call of the turn under way, numbered from 1 by the assistant’s host; 0 outside a turn’s call.
  • DateTime? callStartedAt — When [call] began, by AssistantSession.clock, set by the assistant’s host with it; null before the first.
  • int heardCall — The last call that has said something — a reasoning [note], its first words, or its whole answer returned, tool calls alone included —, 0 for none: a later [call] has said nothing yet, which the dock shows as *Thinkin…
  • ValueListenable<bool> get cancelled
  • void cancel()
• class PluginCallOutcome — What a call came to.
  • const PluginCallOutcome()
  • PluginCallOutcomeWords get words — What labels.dart’s pluginOutcomeText reads of this outcome.
• class PluginCallDone — A call’s value, and what it wrote: new versions’ stems, takes’ names.
  • const PluginCallDone({this.value, this.message, this.messageText, this.written = const []})
  • final Object? value
  • final String? message — An action’s message key and the text it came to in the app’s language.
  • final String? messageText
  • final List<String> written
• class PluginCallFailed — Why a call has no value: failed (with the plug-in’s own [message]), limit ([reason]: time, memory, stack, result, wall), cancelled, hung, refused ([reason]), disabled, noProvider, notAvailable, stale.
  • const PluginCallFailed(this.code, {this.reason, this.message, this.file, this.line, this.column, this.path, this.stage})
  • final String code
  • final String? reason
  • final String? message
  • final String? stage — Where a request door’s refusal came: admission, before anything left the machine, or transport; null for any other failure.
  • final String? path — Where an answer failed the contract, in the answer’s own terms — outputs[0].mime — for the code badResult.
  • final String? file — The plug-in’s own code file the failure came from, and the place in it.
  • final int? line
  • final int? column
  • String? get at — file:line:column, or null where there is no position: what a page and the developer page show after the message.
• enum PluginStatusState — The four states a plug-in’s status may answer (§14.4): whether it can do its work now, in words a person can act on.
  • values: ready, unconfigured, unavailable, degraded
  • static PluginStatusState? byName(String name)
• class PluginCheckResult — What a Check came to.
  • const PluginCheckResult()
• class PluginChecked — What the plug-in said about itself: a state, its own words where it gave any, and the facts it measured.
  • const PluginChecked(this.state, {this.message, this.details = const PluginStatusDetails()})
  • final PluginStatusState state
  • final String? message — The plug-in’s own message, in the person’s language, where it gave one.
  • final PluginStatusDetails details — The facts of its details the app shows, copied; each absent one is unknown.
• class PluginSaysNothing — The plug-in’s code has no status, which api 1 asks of every plug-in.
  • const PluginSaysNothing()
• class PluginCheckFailed — The check did not finish: the call’s own outcome.
  • const PluginCheckFailed(this.failure)
  • final PluginCallFailed failure
• class PluginKeyCheck — A plug-in’s answer about a candidate key.
  • const PluginKeyCheck({required this.accepted, this.message, this.code})
  • final bool accepted
  • final String? message — The plug-in’s own words, shown under the key’s boxes.
  • final String? code — Where the check itself failed: the call’s code.
• class PluginInstallOutcome — What installing a zip came to.
  • const PluginInstallOutcome({this.stem, this.refused, this.field})
  • final String? stem — The installed plug-in, which then asks for consent.
  • final String? refused — A problem’s code when the zip was refused, writeFailed or failed when installing it failed, or reloadFailed when its files were written and the plug-ins could not be read again.
  • final String? field
• class NoPluginRuntime — The runtime of a build that installs none: no plug-in exists.
  • const NoPluginRuntime()

lib/src/project_provider.dart

• variable const AssetProjectSource bundledLibrary — The bundled seed of the shared library, read in place where the app has no files of its own (the web).
• variable final libraryProvider — The shared library of models, platforms and plugins (§14.5).
• variable final projectProvider — The opened project.
• class ProjectImportException — A failed FDX import, with a localizable code and no screenplay or filesystem error text.
  • const ProjectImportException(this.code) — Creates the refusal presented inside the import dialog.
  • final String code — The diagnostic code, such as invalid_xml, read_failed, write_failed or drafts_unsaved.
• variable final projectClosedProvider — Whether the person closed the project: the page then shows no project until one is opened or created.
• class ProjectClosedController
  • void set(bool closed)
• variable final projectSourceKeyProvider — Identifies which source is open, as opposed to its current contents.
• class CreatedProject — What New project made: the project file, which the app opens on Edit (§9.2), and the scene the script starts with.
  • const CreatedProject({required this.project, required this.scene})
  • final VersionStem project
  • final VersionStem scene
• class OpenRefusedException — Another film was not opened, made or copied to because an open draft of this one could not be written first (§7).
  • const OpenRefusedException(this.refusal)
  • final Object refusal — Why the draft was not written.
• variable const Duration kSettleBeforeLeaving — How long the drafts may take to be written before another film opens: as long as closing the window gives them (the app’s DraftsBeforeExit.limit), past which the open is refused.
• class NoLongerWantedException — A write whose caller no longer wanted it when its queue reached it (§7.4): nothing was written.
  • const NoLongerWantedException() — A refusal of a write its caller’s check declined in the queue.
• class ViewerChangedException — A write asked as one viewer that reached its queue under another (§7.4): nothing was written.
  • const ViewerChangedException(this.viewer, this.current) — A refusal of a write asked as [viewer] while the username is now [current].
  • final Author viewer — The author the write was asked as.
  • final Author? current — The viewer when the write’s turn came; null where there is none.
• class ProjectNotOpenedException — A project whose files were written whole but whose folder could not be read back — it would not list, or not load — so it was not opened, and the project on screen stays (§9.2).
  • const ProjectNotOpenedException(this.path, this.cause)
  • final String path — The folder the project was written in, or the session’s label where it has none.
  • final Object cause — What the read answered.
• variable final folderSourceProvider — How a folder on disk is read as a project: the store’s directoryProjectSource, and a test’s stand-in for a folder that writes and will not list.
• variable final folderWatchProvider — How the open film’s folder is watched for documents changed outside the app (§6.1b): the platform’s watchFolder, and a test’s watch over streams of its own.
• class IndexNotPublishedException — A write landed, but the index could not be published after it — the folder would not list — so the view is behind the folder until it is read again (§7.5).
  • const IndexNotPublishedException(this.cause, {this.answer}) — The publication’s failure, [cause], after a gesture whose body answered [answer].
  • final Object cause — What the listing answered.
  • final Object? answer — What the gesture’s writes answered before its publication failed — the stem written, say — so that its caller says what landed; null where the body answered nothing.
• class ProjectController
  • WriteRecord get record — The write record, for a writer made outside the controller — an insertion job’s — so that its writes are in [view] as they land and in the next publication unread (§7.5).
  • Future<void> Function()? beforePublish — Runs once, as a gesture is about to publish its index, and is spent before it runs: the seam where a test types or edits a file between a gesture’s writes and its publication.
  • FilmProject? get baseIndex — [_base], read-only, so a test can see that an overtaken re-read left it alone.
  • FilmProject? get view — The film as every decision reads it (§7.5): the published index with the record’s landed writes of this film and its library laid over it, built without a read; the published index itself while nothing has landed since.
  • FilmProject? get baseView — [baseIndex] with the record’s landed writes laid over it, before any viewer’s pick is applied: what another viewer’s film is resolved from, as [view] is the viewer’s (§7.5).
  • Future<String> copySessionTo(String parentPath) — Copies every file of the open session, including media, into a new folder and opens it there (§4.1).
  • Future<void> openSample() — Opens the sample afresh: a new extraction, made once the film being left has settled, so that an open refused replaces nothing and makes no folder.
  • Future<void> close() — Close project: every open draft is written first, and the film’s documents are sent within what remains of [kSettleBeforeLeaving] (§6.14), then the page shows no project.
  • Future<void> openDirectory(String path) — Opens a folder on disk.
  • Future<VersionStem> importScript({ required String path, required String parentPath, required String epochLabel, }) — Imports a screenplay file into a fresh folder, then opens its complete index without replacing the old film on failure.
  • Future<CreatedProject> createProject({ required String parentPath, required String tag, required Author author, String? name, required String epoch… — Creates a project — <parentPath>/<tag>/ on disk where folders can be made, else a session-only project in memory — writes its manifest (§4.4) and the creator’s first pj version (§8), and opens it once it has been…
  • Future<bool> refresh({bool library = false, String reason = 'asked'}) — Reads the current source again whole, picking up files changed on disk: a publication of kind reread (§7.5).
  • Future<bool> noticeWritten({Map<String, String?> written = const {}, String gesture = 'noticed', bool publish = true}) — Takes files written by something that is no recorded writer into the record, then publishes unless told not to.
  • Future<void> selectProject(String stem) — Answers the project chooser (§4.1) with one of the candidates.
  • ({String choice, bool landed})? inUseRecorded(Entity entity, {Author? viewer}) — The recorded choice, in flight or landed and unpublished, that makes [entity] the version in use, or null.
  • Future<T> publishingOnce<T>(String name, Future<T> Function() body) — Runs [body], every gesture landing its writes meanwhile without publishing them, then publishes the film once (§7.5).
  • Future<void> updateManifest(Map<String, Object?> Function(Map<String, Object?> json) change) — Changes the manifest with the current viewer and guards, one gesture.
  • Future<Entity?> saveEntity(Entity entity, Map<String, dynamic> json, {String? projectKey}) — Saves the viewer’s own version with new content, one gesture.
  • Future<Entity?> saveEntityAs(Entity entity, Map<String, dynamic> json, {String? projectKey, Author? as}) — [saveEntity], written as [as] where given, which must be the viewer ([writingAs]).
  • Future<VersionStem> createEntity({ required EntityType type, required String tag, String? epoch, required String name, String? kind, }) — A new character or location as the viewer’s v1 at [epoch] (ProjectWriter.createEntity), one gesture.
  • Future<VersionStem> createEntityAs({ required EntityType type, required String tag, String? epoch, required String name, String? kind, Author? as,… — [createEntity], created as [as] where given, which must be the viewer ([writingAs]); with [draftLabel], the assistant’s draft, labelled and not picked (ProjectWriter.createEntity).
  • Future<VersionStem> fork(Entity entity, {Map<String, dynamic>? content, String? film, Author? as, String? draftLabel, Future<void> Function()? gate}) — Forks [entity] for the viewer (§13.1), one gesture, and returns the new stem so the caller can show it.
  • Future<void> pinPick(Entity entity, {String? film, Future<void> Function()? gate}) — Pins [entity] as the viewer’s own explicit pick, in their commentary file’s queue, never following official as [setPick] does: the version in use made a choice before a second handle’s version could make it ask (§4.1).
  • Author? writingAs(Author? as) — The author a write goes out as: the viewer, never another handle — the assistant writes as the person (§7.3).
  • Future<({String epoch, VersionStem? project, bool relabelled, String reason})> declareEpoch(String label, {int? year, required String film, require… — Declares an epoch labelled [label] on the project version in use, one gesture (§8.2).
  • Future<VersionStem> createAtEpoch(EntityGroup group, String target, {required String sourceEpoch, required String boundSourceStem, required String… — Makes the viewer’s v1 of a character or location at a missing declared epoch, one gesture (§8.2).
  • Future<List<Map<String,Object?>>> createCastVersions(Entity scene, {required String film, required Author? viewer, String? draftLabel}) — Creates missing cast character versions for a written scene without settling drafts or throwing (§7.3).
  • Future<VersionStem> createOutfit(String character, String epoch, String name, {required String film, required Author viewer, String? draftLabel, Fu… — Creates the viewer’s outfit named [name] for [character] at [epoch], one gesture (Project Specification §9.2).
  • Future<bool> setOfficial(Entity entity, {required bool official}) — Makes [entity] official (§13.2), or clears the pointer when [official] is false.
  • Future<bool> setPick(Entity entity, {Author? viewer, bool unlessExplicitInUse = false, String? Function(Entity now)? unusable}) — Makes [entity] the viewer’s pick (§13.4): the version used from now on.
  • Future<bool> pickFromCheck(Entity entity) — The check on the version row (§13.4): [entity] becomes the viewer’s choice, even where it is already in use.
  • Future<bool> abandonPick(Entity entity) — Abandons the viewer’s pick at [entity]’s epoch: it is removed, and the viewer is back on official (§13.4).
  • Future<bool> keepPick(Entity entity) — Keeps the viewer’s pick, re-dating it so that its stale warning clears (§13.2).
  • Future<({bool wrote, bool pickFollowed, bool parentFollowed})> setDiscarded(Entity entity, {Author? viewer, bool Function(FilmProject project)? sti… — Sets the viewer’s own [entity] aside: the one door for discarding (Project Specification §7, §6.1, §8.5).
  • bool isCurrent(String film) — Whether [film] is the film open now: not closed, not replaced, and not being left — another source asked, or opening.
  • Future<bool> visit(Entity entity) — Records that the viewer has [entity]’s media on screen (§13.4): the one door a page’s visit goes through.
  • Future<bool> deleteTake(String reference) — Deletes the file of the viewer’s own take [reference] names, and its thumbnail, one gesture (§9.0).
• class EpochBindingChangedException — What an epoch’s write was bound to changed while it waited, so nothing was written (§8.2).
  • const EpochBindingChangedException({this.reason = 'viewerChanged'}) — Refuses an epoch’s write whose binding changed, for [reason]: the viewer’s, unless another is said.
  • final String reason — What changed, as a code: viewerChanged, projectNotBound, projectChanged, sourceChanged, targetUndeclared, targetExists or targetExistsDiscarded.

lib/src/provider_funding.dart

• enum ProviderUnavailableReason — A typed refusal that a consumer may later translate into a localized sentence.
  • values: notConfigured, needsKey, needsSignIn, needsCredit, keyInvalid, keyDenied, checking, unknown, unsupportedRoute, dependencyDisabled, transportUnavailable
• variable const kPluginHttpOperation — The operation word for a plug-in’s HTTP call, as [ProviderFunding.funding] is asked about it.
• variable const kConversationOperation — The operation word for a voice conversation on credit (§6.6).
• variable const kTranscriptionOperation — The operation word for dictation’s transcription on credit (§6.6).
• variable const kPortalRefusalCodes — The website’s codes for a refused portal credential, on a 401: the credential is let go ([ProviderFunding.portalRefused]) and nothing is sent again.
• class FundingBinding — A nonsecret opaque funding handle that a job retains by identity.
  • FundingBinding({required this.providerTag, required this.operation}) — Captures only provider and operation, leaving credentials behind the implementation.
  • final String providerTag — The provider whose funding route was resolved.
  • final String operation — The operation the binding authorizes, rather than arbitrary provider work.
• class FundingResult — The resolved own-key, managed-credit or unavailable funding route.
  • const FundingResult() — Creates a typed funding result without admitting work or placing a hold.
• class OwnKeyFunding — A verified own-key route whose opaque binding a submitted job freezes.
  • const OwnKeyFunding(this.binding) — Captures a nonsecret binding for this result.
  • final FundingBinding binding — The implementation-owned binding retained unchanged through collection.
• class CreditFunding — An explicitly supported managed-credit route with an opaque frozen binding.
  • const CreditFunding(this.binding) — Captures a managed route, never inferring support from balance alone.
  • final FundingBinding binding — The implemented route’s binding retained unchanged through collection.
• class FundingUnavailable — An unavailable route, with an explicit refusal rather than an inferred fallback.
  • const FundingUnavailable(this.reason) — Captures why funding is unavailable.
  • final ProviderUnavailableReason reason — The refusal a consumer translates when it shows the route.
• typedef typedef PortalAccess — Credit admission headers or the cause and code that prevented admission.
• class ProviderFunding — The host-owned funding resolver, whose queries never place holds or submit work.
  • const ProviderFunding() — Creates a resolver without credential, account or transport work.
  • static ProviderFunding get current — The installed resolver, not configured by default.
  • static void install(ProviderFunding resolver) — Installs a resolver without querying or activating it.
  • static Stream<void> get installations — Signals replacement to observers that already read the default.
  • int get generation — The revision advanced when credential, account or configuration bindings change.
  • Stream<void> get changes — Signals after the resolver generation changes.
  • Future<FundingResult> funding(String providerTag, String operation) — Resolves a nonsecret route without a hold, paid admission or silent invalid-key fallback.
  • Future<bool> creditReady(String platform) — Whether credit can fund a plug-in HTTP call on [platform], without credentials, admission or a stored-key check.
  • Future<Map<String, String>?> portalHeaders(String platform, String operation, String operationId) — The headers a request on credit carries — the bearer and the portal credential for [operation]’s scope — or null where there is no credit (§6.6).
  • Future<PortalAccess> portalAccess(String platform, String operation, String operationId, {Future<void>? abort}) — Acquires credit admission with cancellation and its refusal cause.
  • Future<FundedReceipt?> receiptCancellable(String platform, String operation, String operationId, {Future<void>? abort}) — Reads a receipt with cancellation where the implementation supports it.
  • Future<void> endCancellable(String platform, String operation, String operationId, {Future<void>? abort}) — Ends an operation with cancellation where the implementation supports it.
  • void portalRefused(String platform, String operation, String operationId) — The website refused the portal credential of [operation]’s scope (a 401): it is let go, so the next gesture asks anew; nothing is sent again.
  • Future<FundedReceipt?> receipt(String platform, String operation, String operationId) — The operation’s receipt, GET /v1/portal/operations/{id}; null where it has not settled or could not be read.
  • Future<void> end(String platform, String operation, String operationId) — POST /v1/portal/operations/{id}/end, once; its outcome is logged and nothing waits on it.
  • void balanceMoved(String reason) — Credit may have moved — a call on credit closed, or an end was answered — so the balance is read again; [reason] names the trigger in the log (§6.6).
  • void balanceMovedCancellable(String reason, {Future<void>? abort}) — Refreshes credit after a call, stopping that read with the turn’s network work.
• typedef typedef FundedReceipt — What a funded operation’s receipt says was charged and released, in whole US cents, and its id on the portal.
• class NoProviderFunding — The inert resolver, which has no configured or credit-backed route.
  • const NoProviderFunding() — Creates a resolver that never consults a credential or service.
• class FundingResolverSnapshot — An observed resolver and its revision, without performing a funding query.
  • const FundingResolverSnapshot(this.resolver, this.generation) — Captures the installed resolver and the generation observed with it.
  • final ProviderFunding resolver — The host-owned door a user action may query outside build.
  • final int generation — The revision under which the resolver was observed.

lib/src/queue_runner.dart

• variable final queueRunnerProvider — Runs the queue’s passes; the default answers not available, the app’s composition runs the render queue.
• function bool isQueueComplete(SetRecord record) — A queue is complete only with at least one item and a take or error on every item (§6.15).
• class QueueRunner — The queue page’s doors to a pass and to its items’ jobs (§6.15).
  • Future<String?> submit(BatchStem stem, {Set<int>? only}) — Runs one pass over the queue [stem]: null where it went through its items, else the code of why not.
  • Future<QueuePreparation> prepare(InsertionTarget target) — Prepares the saved words at [target] without writing or submitting anything.
  • Future<QueuePreparation> prepareBeforeWriting(InsertionTarget target) — Whether a prompt is worth writing for [target], before anything is paid (§9.3).
  • Future<bool> finishInterrupted(BatchStem stem) — Ends a pass that ended without its end, submitting nothing; false, with nothing written, where it may not.
  • Future<bool> markNotSubmitted(BatchStem stem, int n) — Mark as not submitted on the unresolved item [n]; false, with nothing written, where it may not.
  • bool isLive(BatchStem stem) — Whether a pass of [stem] is under way in this app.
  • QueueJob? job(String id) — The live job [id], else its terminal view heard this session without actions, else null.
  • Future<String?> act(String id, String action) — Sends [action] — one of [QueueJob.actions] — to job [id]: null where it was accepted, else the refusal’s code.
  • Stream<void> get changes — Told when a pass starts or ends, or any job changes.
  • Stream<QueueChainFailure> get chainFailures — Failed terminal outcome writes, heard by the page while it is open.
• class QueueChainFailure — A terminal outcome the queue could not write into its record.
  • const QueueChainFailure({required this.stem, required this.n, required this.phase, required this.code, required this.message}) — A failed write, retaining its item, terminal phase and failure’s full message.
  • final BatchStem stem — The queue record that could not be written.
  • final int n — The item’s stable number.
  • final String phase — The heard terminal phase: done, failed or cancelled.
  • final String code — The write failure’s code.
  • final String message — The write failure’s message as it came.
• class QueuePreparation — A place’s preparation across the state seam, without a render UI type (§6.15).
  • const QueuePreparation({required this.ready, this.reason, this.route = 'none', this.model, this.platform, this.cost, this.item}) — A preparation or its refusal, with an unknown cost kept null.
  • final bool ready — Whether its frozen item is ready to submit; on a prepareBeforeWriting answer, only leave to write.
  • final String? reason — The refusal’s code, or null when ready.
  • final String route — local, server, paid, lent, or none before a route opens.
  • final String? model — The model where a candidate opened.
  • final String? platform — The opened candidate’s platform.
  • final Money? cost — Amount and currency, or null when unknown.
  • final Map<String, Object?>? item — The frozen queue item as JSON, without its record number; null when refused or from prepareBeforeWriting.
• class QueueJob — A job a queue item became, as its row shows it: the phase, its state code, its take once done, and its actions.
  • const QueueJob({required this.phase, this.state = '', this.take, this.actions = const []}) — A job of its parts.
  • final String phase — The job’s phase by name: queued, working, waiting, needsAttention, done, failed, cancelled.
  • final String state — The job’s state code, which the Activity page’s sentence reads.
  • final String? take — The take’s reference once done; null before, or where the job made none.
  • final List<String> actions — The codes of the actions the job offers now, as the Activity page offers them: stop, dismiss, ….
• class UnavailableQueueRunner — The runner where none is installed: every call answers not available.
  • const UnavailableQueueRunner() — The runner of a build without the render queue.

lib/src/recording_provider.dart

• class RecordingFlag — Whether the issue recorder is running (Software Specification §6.8).
  • void set(bool recording)
• variable final recordingProvider

lib/src/render_defaults_provider.dart

• variable final renderDefaultsProvider — Settings → Models’ default model for each role and stage, as the preference render.defaults holds them (§9.4).
• class RenderDefaultsController — Reads and keeps render.defaults; every read and write is logged with the value.
  • static const key — The preference’s key.
  • Map<String, Object?>? entry(String kind, String stage) — The default for [kind] at [stage] (prototype or final); null where none is chosen.
  • Future<bool> choose(String kind, String stage, Map<String, Object?>? entry) — Chooses [entry] as the default for [kind] at [stage], or clears it where [entry] is null; the other entries stand.

lib/src/render_jobs_provider.dart

• class RenderJobLine — One render job under way, as the dock’s activity line names it (§6.15).
  • const RenderJobLine({required this.job, required this.film, required this.stem, required this.place, required this.name, required this.phase, requi… — The job [job] rendering into [place] of [stem] of [film], named [name], in [phase] with [stateCode].
  • final String job — The insertion job’s id.
  • final String film — The project key of the film the job renders for; empty where its place key names none.
  • final String stem — The stem of the entity or scene the job renders for; empty where its place key names none.
  • final String place — The media group the job renders into: a slot’s group (a path slot’s path), a block’s group, or takes.
  • final String name — The job’s own name, else the entity’s as the open film reads it where the job is that film’s, else the stem.
  • final String phase — queued, working or waiting; needsAttention only for an unconfirmed stop.
  • final String stateCode — The job’s state code, as its view says it.
  • final String? placeKey — The job’s place key, as the service holds it.
  • final bool stopping — Whether a Stop reached the job and it is settling.
  • final bool stoppable — Whether the job offers Stop and no Stop has reached it yet.
  • final bool dismissable — Whether the job offers Dismiss.
  • bool get unconfirmed — Whether the job waits on a stop its producer could not confirm: it no longer runs (§6.13).
  • Map<String, Object?> get toLog — The line as the log carries it.
• variable final renderJobsProvider — Every producer’s job queued, working or waiting, and one whose stop could not be confirmed — the installed service says that as needsAttention:stopUnconfirmed —, in the service’s order; logged `assistant.activity.ch…
• function Future<JobActionAck?> stopRenderJob(InsertionService service, RenderJobLine line) — Asks [service] to stop [line]’s job through its own Stop, logged assistant.activity.stop.outcome; answers the service’s acknowledgement, null where asking threw, which is logged and not rethrown.
• function Future<JobActionAck?> dismissRenderJob(InsertionService service, RenderJobLine line) — Asks [service] to dismiss [line]’s job, a stop its producer could not confirm, logged assistant.activity.dismiss and its outcome; the line goes when the service’s views drop the job, never before.

lib/src/route_events.dart

• enum RouteChange — What a navigator did: a route pushed, popped, replaced or removed.
  • values: push, pop, replace, remove
• class RouteEvent — One change of the navigator, as the issue recorder writes it (§6.8).
  • const RouteEvent(this.change, this.kind, this.name)
  • factory RouteEvent.of(RouteChange change, Route<dynamic> route)
  • final RouteChange change
  • final String kind
  • final String? name
  • static String kindOf(Route<dynamic> route) — The kind of [route], by its type rather than its type’s name, which a release build minifies.
• class RouteListener — Hears the navigator’s changes through [RouteEvents].
  • void onRoute(RouteEvent event)
• class RouteEvents — The seam for a route opening or closing (§6.8).
  • static final RouteEvents instance — The observer lib/app.dart installs.
  • void addListener(RouteListener listener) — [listener] hears every change from now on.
  • void removeListener(RouteListener listener) — [listener] hears no more.

lib/src/route_words.dart

• function String routeOrigin(AppLocalizations l10n, Map<String, Object?> route, {String? slotLabel, String? programLabel, String? destinationLabel}) — Formats the decided origin without choosing or checking any route.
• function String pluginRouteLine(AppLocalizations l10n, String tag, Map<String, Object?> route, {String? destinationLabel, String? pluginLabel}) — Names the plug-in and the exact decided slot, program, funding or destination, including a refused choice.
• function String renderRouteLine(AppLocalizations l10n, String tag, {required String funding, String? programLabel, String? planLabel, String? destinationLab… — Names a render route by its plug-in and origin (§9.4).

lib/src/scene_timeline_provider.dart

• variable final timelineEngineProvider — Makes the engines scenes play and export through: by default the fake, each wrapped in its log.
• variable final sceneTimelineProbeProvider — The engine’s probe as the timeline measures with it: one probe per file, its answer kept for the engine’s life.
• variable final mediaAudioProbeProvider — Whether a clip has sound, measured once at insertion with the engine the timeline measures with (§9.0): its probe’s audio stream, or the code and message of its refusal or failure (unavailable where this platform ha…
• variable final sceneTimelineProvider — The timeline of the scene whose version stem is the argument; null, said in the log, where no project is open or it holds no such scene.

lib/src/script_focus.dart

• class ScriptFocus — The block open in a scene’s script editor, and who opened it.
  • const ScriptFocus({required this.stem, required this.blockId, required this.index, required this.by}) — The block [blockId] at [index] of [stem]’s script, opened by [by].
  • final String stem — The scene’s file stem, whose form’s editor has the block open.
  • final String? blockId — The block’s bl_<n>; null for a block that has none yet.
  • final int index — The block’s place in the scene’s list, 0 first.
  • final String by — Who opened it: person for the editor’s own reasons, timeline for an opening the timeline asked.
  • bool sameBlock(ScriptFocus other) — The same block of the same scene, whoever opened it: what a close must name to clear it.
• variable final scriptFocusProvider — The block the script editor has open, published by the editor after the frame that opened or condensed it.
• class ScriptFocusController — Holds the block open in the script editor; the editor’s two doors, [opened] and [closed], are its only writers.
  • bool get live — Whether its scope still stands.
  • void opened(ScriptFocus focus) — [focus] is the block now open.
  • void closed(ScriptFocus focus) — [focus] condensed: cleared only where it is the block current.
• class ScriptFocusRequest — The dock’s request that the editor of [stem] open a block.
  • const ScriptFocusRequest({required this.stem, required this.blockId, required this.index, required this.serial}) — The request numbered [serial] for the block [blockId] at [index] of [stem]’s script.
  • final String stem — The scene’s file stem: only the editor of that scene answers.
  • final String? blockId — The block’s bl_<n>, by which the request is delivered wherever the block now is; null where it has none.
  • final int index — The block’s place when it was asked: what delivers a request with no [blockId].
  • final int serial — The request’s number, raised by every ask.
• variable final scriptFocusRequestProvider — The last request for a block to open; the editor of its scene listens.
• class ScriptFocusRequests — Holds the last request for a block to open; [ask] is its one door.
  • void ask(String stem, String? blockId, int index, {required String by}) — Asks the editor of [stem] to open the block at [index] ([blockId] where it has one), on behalf of [by].
• class TimelineCharge — Who is in charge of which block is open in the script, and whether the dock is being pressed.
  • const TimelineCharge({this.following = false, this.dockPressed = false}) — The charge: the person’s, with no press in the dock, unless said otherwise.
  • final bool following — Whether the timeline is in charge of which block is open, from a press in the dock until the person takes it back.
  • final bool dockPressed — Whether a pointer is down in the dock: the one press outside a block that does not condense it.
• variable final timelineChargeProvider — Who is in charge of which block is open in the script: the editor, or the timeline.
• class TimelineChargeController — Holds [TimelineCharge]; written from gestures and focus listeners only, never from a widget’s lifecycle.
  • void follow(bool on, {required String how}) — The timeline takes charge ([on]) or gives it back, [how] saying why.
  • void dockPress(bool down) — A pointer goes down in the dock ([down]), or up or cancelled there.

lib/src/script_row_text.dart

• class ScriptRowText — What a row of the script says, wherever it is drawn — the tree’s Script branch, the Script page and a folder’s contents — so that the three read alike: the row’s words, the page it opens and whether a reader flags it,…
  • const ScriptRowText({required this.label, this.detail, this.tooltip, this.shortName, this.selection, this.hasProblem = false, this.isDeleted = false})
  • final String label — Name first, as the library’s rows are.
  • final String? detail — A folder’s kind in words, a scene’s short name — or the reason the row is flagged.
  • final String? tooltip — The stem, since the row shows the name; a longer reason for a cycle.
  • final String? shortName — A folder’s short name, which its row shows nowhere: for a filter by name or tag.
  • final Selection? selection — The page the row opens; null for an entry that names nothing the project has.
  • final bool hasProblem
  • final bool isDeleted — The version drawn is in the recycle bin (§7): the row keeps its place, struck, with deleted as its detail, and opens that very version.
  • factory ScriptRowText.of(AppLocalizations l10n, ScriptRow row) — The words for [row].
• function String? folderKindDetail(AppLocalizations l10n, Entity folder) — A folder’s kind in words: the vocabulary’s in the reader’s language and in lower case, as every detail of the tree is.

lib/src/script_view.dart

• enum ScriptViewMode — How the Script tab of a folder or of the whole film is read: as a screenplay page, a grid of scene cards, or a timeline of the scenes by page length.
  • values: page, grid, timeline
• enum ScriptTimelineColouring — What the Script tab’s timeline colours its scenes by: the scene grid’s stripe, or a hue for each location.
  • values: board, location
• class ScriptViewState — How a reader is looking at the script of the open film: the view, and what an aggregate is narrowed to (§9.3).
  • const ScriptViewState({ this.mode = ScriptViewMode.page, this.colouring = ScriptTimelineColouring.board, this.character = '', this.location = '', t… — A reading in [mode] narrowed by the filters given; with none, the whole script as a page.
  • final ScriptViewMode mode — Whether a folder’s and the whole film’s script are read as a page, a grid of scene cards or a timeline.
  • final ScriptTimelineColouring colouring — What the timeline colours its scenes by; a way of looking like [mode], so Clear keeps it.
  • final String character — The character’s tag a reader has narrowed to; empty for every character.
  • final String location — The location’s tag a reader has narrowed to; empty for every location.
  • final String resource — The prop, outfit or other resource’s tag a reader has narrowed to; empty for all of them.
  • final bool interior — Whether scenes inside are asked for: with [exterior], a pair that asks nothing where neither is chosen.
  • final bool exterior — Whether scenes outside are asked for: with [interior], a pair that asks for either where both are chosen.
  • final bool day — Whether scenes by day are asked for — any time not plainly night: with [night], a pair like the other.
  • final bool night — Whether scenes at night are asked for, by the words a slug line uses for it: with [day], a pair like the other.
  • final String search — Words that must appear among the words the page draws for a scene; empty for every scene.
  • bool get isFiltered — Whether anything at all narrows what is shown.
  • Object get filters — The filters as one value, equal where they narrow alike, the mode and the colouring left out.
  • Map<String, Object?> get logged — The filters as the log records them; the search’s words are logged only once a search settles (§9.3).
  • static List<String> resourcesOf(Entity scene) — The props, outfits and resources [scene] names, by tag: an entry is a tag or a map naming its tag ({"prop": "chart", "epoch": "default"}, Project Specification §10).
  • Map<String, Object?>? failure(Entity scene, SceneCard card, String words) — Why [scene] is not shown under these filters, null where it is: the first filter that failed and what it compared.
  • ScriptViewState copyWith({ ScriptViewMode? mode, ScriptTimelineColouring? colouring, String? character, String? location, String? resource, bool? i… — This reading with the values given changed and the rest kept.
• class ScriptViewController — The view and filters the Script tab is read with, kept across the tree and reset when another film opens (§9.3).
  • void setMode(ScriptViewMode mode) — Shows the script the other way, keeping whatever it is narrowed to.
  • void setColouring(ScriptTimelineColouring colouring) — Colours the timeline’s scenes another way, keeping the view and whatever the script is narrowed to.
  • void setCharacter(String tag) — Narrows to one character, or to every character where [tag] is empty.
  • void setLocation(String tag) — Narrows to one location, or to every location where [tag] is empty.
  • void setResource(String tag) — Narrows to one prop, outfit or resource, or to all of them where [tag] is empty.
  • void setSearch(String words) — Narrows to scenes whose drawn words hold [words]; empty shows every scene.
  • void toggleInterior() — Turns the interior chip on or off.
  • void toggleExterior() — Turns the exterior chip on or off.
  • void toggleDay() — Turns the day chip on or off.
  • void toggleNight() — Turns the night chip on or off.
  • void clear() — Shows everything again, keeping the view and the colouring the reader chose.
• variable final scriptViewProvider — How the open film’s script is being read: the view and its filters (§9.3).

lib/src/selection.dart

• class Selection — What the detail pane shows.
  • const Selection()
  • List<String> get matchKeys — Keys the tree uses to find the row for this selection, most specific first.
• class ProjectOverviewSelection — The project’s landing: its selected version, or the chooser or diagnostics when none is selected.
  • const ProjectOverviewSelection()
• class ScriptSelection — The script: what the project file in use holds, in order, and what is not in it.
  • const ScriptSelection()
• class CategorySelection — All entities of one type, as a list.
  • const CategorySelection(this.type)
  • final EntityType type
• class EntitySelection — One entity (all epochs and versions), optionally focused on one epoch and one version file.
  • const EntitySelection(this.type, this.tag, {this.epoch, this.stem})
  • final EntityType type
  • final String tag
  • final String? epoch — The epoch to show first; null for spec entities or “the first one”.
  • final String? stem — The full stem of the version to show first; null for “official or the highest”.
• class BatchSelection — One render batch record.
  • const BatchSelection(this.stem)
  • final String stem — e.g. rd_8af0_maria
• class PendingSelection — The viewer’s pending set of one type (Project Specification §12.7): its record, or the empty page saying what fills it.
  • const PendingSelection(this.type) — The viewer’s pending set of [type].
  • final EntityType type — The set’s type: a comp, an assistant session or a render batch’s queue.
• class OtherFilesSelection — The files the grammar does not describe, and companion files it does.
  • const OtherFilesSelection()
• function Map<String, Object?>? selectionToJson(Selection? selection) — A [Selection] as data, in the shape the MCP Specification’s §4.2 gives it: {"kind": "overview"}, {"kind": "script"}, {"kind": "category", "type": "ch"}, `{“kind”: “entity”, “type”: “sc”, “tag”: “5”, “epoch”: nul…

lib/src/semantics_walk.dart

• function SemanticsOwner? semanticsOwnerOf(FlutterView view) — The semantics owner of [view]’s render view — each view has a pipeline of its own.
• function bool walkSemantics(SemanticsNode node, bool Function(SemanticsNode node) visit) — Visits [node] and its descendants depth-first, in the tree’s child order, until [visit] answers false.
• function SemanticsNode? findByIdentifier(SemanticsNode root, String identifier) — The first node, in walk order, whose identifier is [identifier].
• function String firstLine(String label) — A label’s first line: a tab’s label carries its position (“Tab 3 of 5”) on the line below its text.
• function List<SemanticsNode> findByLabel(SemanticsNode root, String label) — The nodes whose label, or whose label’s first line, is [label], in walk order.
• function List<SemanticsNode> tabNodes(SemanticsNode root) — The tabs of every tab bar on screen, in order.
• function SemanticsAction? activationOf(SemanticsData data) — What a click on a node does, as a screen reader asks for it: tap, or expand / collapse where the control offers no tap.
• function SemanticsNode? nodeToTap(SemanticsNode node) — The node a tap on [node] acts on.
• function Rect globalRect(SemanticsNode node, double devicePixelRatio) — Where [node] is on the view, in logical pixels.
• variable const List<String> valueIdentifiers — The identifiers under which a value travels: what a person typed into a text field, and the two paths the developer page shows.
• class CanonicalTextValue — A rendered field’s canonical committed value, released only by its current registration.
  • CanonicalTextValue(this.identifier, this.read) — Registers a source reader under the consumer’s exact field identifier.
  • final String identifier — The consumer-owned field identifier used by recorder sampling.
  • final String Function() read — Reads committed source without the field’s provisional span or shown placeholders.
  • void end() — Removes this registration without clearing a newer rendered owner of the same identifier.
• class LiveDictation — One live dictation whose provisional text must stay out of the recorder’s values.
  • LiveDictation(this.identifier, String committedValue) — Registers a field with its canonical committed baseline before capture starts.
  • final String identifier — The consumer-owned field identifier, shared by the semantics and tape gates.
  • final String committedValue — A safe baseline used only when the recorder has not sampled this field before.
  • void end() — Removes only this attempt after the committed or restored value reaches semantics.
• function bool isLiveDictation(String identifier) — Whether an identifier currently holds speech that has not reached its final field state.
• function bool isLiveDictationControl(String identifier) — Whether an identifier names a live field or one of its dotted derived controls.
• function bool isDictationCaption(String identifier) — Whether an identifier belongs to a live caption rather than a committed field value.
• function Map<String, Object?> semanticsToData(SemanticsNode node, {required double devicePixelRatio, String? identifierAbove}) — [node] and everything below it as data (§3.3).
• enum SettleEnd — How a [settleFrames] wait ended.
  • values: idle, stable, cap
• variable const Duration kSettleQuiet — How long the semantics tree must stay without an update for [settleFrames] to end stable: the drawer’s slide, which runs on after the tree has its last update, takes 200 ms.
• function Future<({SettleEnd end, int? quietAgeMs})> settleFrames({ Duration timeout = const Duration(seconds: 5), SemanticsOwner? owner, }) — Waits for the frame that shows what a change did, then for the animations it started — a tab sliding, a dialog fading in — for at most [timeout].
• function Future<void> nextFrame() — The end of the next frame, scheduling one.
• function Map<String, String> tabIdsOf(AppLocalizations l10n) — The tab ids by the label each wears in [l10n].
• function List<(String, SemanticsNode)> entityTabs(SemanticsNode root, AppLocalizations l10n) — The tabs on screen under [root], an entity page’s or Settings’, each with its id.
• function String? currentTab(SemanticsNode root, AppLocalizations l10n) — The id of the selected tab, an entity page’s or Settings’, or null when none is on screen.
• variable const settingsPagePicker — The identifier of Settings’ pull-down of pages, which stands in for its list beside the page below 700 px of window (§9.4).
• function String? settingsPickerPage(SemanticsNode root, AppLocalizations l10n) — The page id — general, keys or plugins — that Settings’ pull-down of pages shows under [root], or null where it is not on screen.
• function Map<String, String> settingsPageIds(AppLocalizations l10n) — Settings’ page ids by the name each wears in [l10n]: what a tab or the pull-down of pages says, and what a choice of one is found by.
• class SemanticsHit — What a pointer at a point reaches, as the issue recorder names it (§6.8).
  • const SemanticsHit({ this.identifier, this.label, this.tooltip, this.within, required this.role, this.action, this.rect, this.reachedByLabel = fals…
  • final String? identifier — The identifier a tap by identifier reaches this control through — the control’s own, or a wrapper’s that holds no other control — checked the way replay finds it: the first node on screen with that identifier.
  • final String? label — The control’s label, its first line.
  • final String? tooltip — The control’s tooltip, its first line, when it differs from the label.
  • final String? within — The nearest identifier above a control that a tap by identifier does not reach — the row a chip sits in.
  • final String role — button, tab, textField, menuItem or other.
  • final String? action — What a click does: tap, expand or collapse ([activationOf]); null when nothing under the point takes a click.
  • final Rect? rect — The control’s rect on the view, in logical pixels.
  • final bool reachedByLabel — Whether a tap by [label] reaches this control.
  • bool get resolved — Whether replay can reach the control: by its identifier or its label.
• function SemanticsHit? semanticsNodeAt(SemanticsNode root, Offset point, double devicePixelRatio) — The control a click at [point] (logical pixels of the view) reaches, named the way replay acts on it (§6.8).
• function SemanticsNode? findById(SemanticsNode root, int id) — The node whose id is [id] under [root], or null.
• function SemanticsHit describeControl(SemanticsNode root, SemanticsNode hit, double devicePixelRatio) — Names the hit control for replay: its identifier, its label and tooltip as they are, its role and action.
• function List<(String, String)> textValues(SemanticsNode root) — Collects editable field values in walk order, with unique identifiers.
• function String? focusedTextIdentifier(SemanticsNode root) — The identifier of the text field that has the focus, when its value travels ([valueIdentifiers]); null otherwise.

lib/src/sets_provider.dart

• variable final pendingSetProvider — The viewer’s pending set of a type (Project Specification §12.7): a comp, an assistant session or a render queue.
• variable final setHistoryProvider — Every record of a type that is no author’s pending one, newest first (§12.7).
• variable final pendingSetsProvider — The one door the pending sets are written through: [PendingSets] over the opened project’s controller.
• class PendingSets — Adds to, removes from and commits the viewer’s pending set of a type (§12.7), for comps, sessions and queues alike, and updates one of the viewer’s records by its stem.
  • SetRecord? pending(EntityType type) — The viewer’s pending set of [type] as decisions read it (ProjectController.view, §7.5), or null.
  • Future<SetRecord> add(EntityType type, Map<String, Object?> item) — Appends [item] to the viewer’s pending set of [type], creating the record where none is; answers the record.
  • Future<SetRecord?> remove(EntityType type, int n) — Removes the item numbered [n] from the viewer’s pending set of [type]; next_item is kept, so no n is reused.
  • Future<SetRecord?> commit(EntityType type, String status, {Map<String, Object?> members = const {}}) — Sets the viewer’s pending set of [type] to [status], with [members] — the type’s own top-level members — beside.
  • Future<SetRecord?> update(BatchStem stem, Map<String, dynamic>? Function(SetRecord record) change, {String? projectKey}) — Changes the viewer’s own record [stem], whatever its status: [change] answers the new document, or null for nothing to write.

lib/src/settings_provider.dart

• variable final sharedPreferencesProvider — The preference store, supplied by main.
• function String? dictationDeviceLabelFor(String? id, String? stored) — The name kept for the microphone [id], from its preference [stored] — the id and the name together — or null where the two do not belong together (§9.6).
• variable final developmentModeDefaultProvider — Whether development mode is on before anyone has chosen (§9.5): on wherever the build has the switch.
• variable final developmentModeAvailableProvider — Whether this build has development mode ([kDevelopmentModeAvailable]).
• enum SettingsWrite — A preference whose last write did not reach the store (§9.4): its value stays for the session, and Settings says so — with Try again for the username and the new project’s folder.
  • values: viewerHandle, newProjectParent, exportEncoder, warnInsteadOfRefuse
• enum ViewerFallback — Why a stored username stood for [kDefaultViewerHandle] when the preferences were read (§9.4); logged by name.
  • values: missing, blank, invalid, unreadable
• enum ViewerChangeOutcome — What a change of the username came to ([SettingsController.setViewerHandle]).
  • values: changed, unchanged, invalid, refused, superseded
• class ViewerChange — The answer of [SettingsController.setViewerHandle]: what the change came to, and why where it did not happen.
  • const ViewerChange(this.outcome, {this.problem, this.refusal})
  • final ViewerChangeOutcome outcome — What the change came to.
  • final ShortNameProblem? problem — Why the text is not a handle, where [outcome] is [ViewerChangeOutcome.invalid].
  • final Object? refusal — What kept an open draft from being written — its write’s error, or [DraftsNotSettledException] — where [outcome] is [ViewerChangeOutcome.refused].
• class RecentProject — A project folder the user opened before, for the sidebar menu.
  • const RecentProject({required this.path, required this.name})
  • final String path
  • final String name — The film’s name when it was last opened, else the folder name.
  • Map<String, Object?> toJson()
  • static RecentProject? fromJson(Object? json) — Null for anything that is not a {path, name} object, so an unreadable entry is dropped rather than crashing the settings.
• class ProjectRecordRef — The record id this device made for a project’s folder (§6.6), and whether the account has answered for it.
  • const ProjectRecordRef({required this.id, required this.recorded}) — The id [id], [recorded] once the account answered the create.
  • final String id — The record’s uuid, made before the create and sent again on its replay.
  • final bool recorded — True once the account answered the create; false while the id is kept but unanswered.
  • Map<String, Object?> toJson() — The entry as the projectRecords preference keeps it.
• enum RecordSave — Whether [SettingsController.keepRecord]’s write reached the store.
  • values: saved, failed
• class Settings — User preferences.
  • const Settings({ this.themeMode = ThemeMode.system, this.viewerHandle = kDefaultViewerHandle, this.sidebarWidth = defaultSidebarWidth, this.assista…
  • static const double defaultSidebarWidth
  • static const double defaultAssistantWidth — The docked assistant’s width until the person drags it: its minimum, which leaves the page the most (§9.1).
  • static const double defaultTimelineHeight — The timeline dock’s height until the person drags it: its narrow row, since the page is mostly the script (§9.1).
  • static const exportEncoders — The export encoder’s values a person may choose (§9.4, §19): auto, the engine’s own choice, and software.
  • static const int maxRecentProjects — How many opened folders the menu remembers.
  • final ThemeMode themeMode
  • final String viewerHandle — The username: the handle this session writes as and whose versions count as “mine” (§6.1 author-first resolution, §13.3 column one) — [kDefaultViewerHandle] where none is chosen (§9.4).
  • final double sidebarWidth
  • final double assistantWidth — The docked assistant’s width, as the person last dragged it; the frame lays it out narrower where the window cannot hold it beside the page’s floor, and keeps this (§9.1).
  • final double timelineHeight — The scene page’s timeline dock’s height, as the person last dragged it; the page lays it out between its narrow row and half the page, and keeps this (§9.1).
  • final String exportEncoder — The encoder the dock’s MP4 export asks for, one of [exportEncoders]: auto (the graphics card’s where one opens, else the software one) or software (§9.4, §19).
  • final Locale? locale — The chosen language, or null to follow the platform.
  • final bool verboseLogs — Log at debug level instead of info (filmopen_store’s app_log.dart).
  • final List<RecentProject> recentProjects — Most recent first.
  • final String? libraryPath — A shared-library folder chosen by the user, or null for the app’s own.
  • final bool accountSignedIn — Whether a filmopen.ai session is kept on this machine.
  • final bool compareChangesOnly — Whether Compare hides the rows whose two versions are equal (§9.3’s Show changes only); true until chosen otherwise.
  • final bool driveSignedIn — The Google sign-in hint; drawing it never reads the credential store.
  • final Map<String, String> sharingFolders — This machine’s sharing folder per film, never written into a manifest.
  • final bool warnInsteadOfRefuse — Development mode (§9.5): a rule about who may do what warns instead of refusing.
  • final String? dictationDevice — The microphone dictation records from (§9.6): an id the system gave, or null for the system’s default.
  • final String? dictationDeviceLabel — The name [dictationDevice] had when it was chosen, for Settings to show without asking the system; null with it.
  • final String? dictationEngine — The speech service dictation transcribes with (§9.6), by the id filmopen_dictation gives it, or null for its default.
  • final String? newProjectParent — The folder New project last made a project in on this machine (§9.2), or null: kept apart from the projects opened, so that browsing to another film does not move where the next one is made.
  • final Set<SettingsWrite> unsaved — The preferences whose last write did not reach the store; their values stay for the session (§9.4).
  • Map<String, ProjectRecordRef> get projectRecords — The record id kept per project folder on this device (§6.6), apart from [recentProjects], whose cap and menu remove entries.
  • ProjectRecordRef? recordOf(String path) — The record id kept for the folder at [path], or null where none was made on this device.
  • Guards get guards — The policy every write of this session applies (ProjectWriter).
  • static ({String handle, ViewerFallback? fallback}) resolveHandle(String? stored) — The username [stored] stands for (§9.4), with why where it is not [stored] itself.
  • Author? get viewer — The viewer: the author [viewerHandle] names, read by [resolveHandle] — never null, since a username that is not a handle is [kDefaultViewerHandle].
  • Settings copyWith({ ThemeMode? themeMode, String? viewerHandle, double? sidebarWidth, double? assistantWidth, double? timelineHeight, String? expor…
• variable final settingsProvider
• class SettingsController
  • Map<String, Object?>? renderLast(String media, String stage) — The render dialog’s last options for [media] (image or video) at the stage [stage], as [setRenderLast] kept them; null where there are none, or the entry is no object (§9.3).
  • void setRenderLast(String media, String stage, Map<String, Object?> entry) — Keeps [entry] as the render dialog’s last options for [media] at the stage [stage]; the other entries stand (§9.3).
  • Future<void> retryWrite(SettingsWrite which) — Writes [which] again as it stands for this session: Try again under a preference that could not be saved (§9.4).
  • void rememberNewProjectParent(String path) — Remembers [path] as the folder New project proposes next (§9.2): called once a project was made there and opened, never for a cancel or a refusal.
  • String? sharingFolderFor(String projectKey) — This machine’s sharing folder for the film, where one was chosen.
  • void setSharingFolder(String projectKey, String? path) — Keeps the path on this machine alone; null removes the film’s choice.
  • void setDriveSignedIn(bool signedIn) — Keeps the Google sign-in hint without consulting the credential store.
  • void setLocale(Locale? locale) — Null follows the platform language.
  • void setThemeMode(ThemeMode mode)
  • Future<ViewerChange> setViewerHandle(String handle) — Changes the username, through the one transition every caller uses — Settings’ box, the agent’s set_viewer, the agent’s restore at quit — so that nothing typed under one username is written as the next (§9.4).
  • Future<bool> viewerStored() — Waits for the username’s last write to the store, a later one begun meanwhile included, and answers whether it reached it: false where it failed, the username then this session’s alone ([Settings.unsaved]).
  • void supersedeViewerChange({required String reason}) — Supersedes the change of the username waiting on the open drafts, if any, so that it never commits — what an account’s leaving does to a change asked for under it (§6.6).
  • Future<void> viewerSettled() — Completes once no change of the username is waiting on the open drafts ([setViewerHandle]), at once where none is: a caller about to write as the username — a dialog that creates a file — reads it after this, so that…
  • void setSidebarWidth(double width)
  • Future<void> setAssistantWidth(double width) — Keeps [width] as the docked assistant’s, and answers once the store has it or has failed to.
  • Future<void> setTimelineHeight(double height) — Keeps [height] as the timeline dock’s, and answers once the store has it or has failed to.
  • Future<void> setExportEncoder(String encoder) — Keeps [encoder] (one of [Settings.exportEncoders]) as the export’s, and answers once the store has it or has failed to; any other value is refused, nothing changed.
  • Future<void> setCompareChangesOnly(bool value) — Keeps [value] as Compare’s Show changes only, and answers once the store has it or has failed to.
  • void setVerboseLogs(bool verbose)
  • void addRecentProject(String path, String name) — Puts [path] at the top of the recent list, replacing an older entry for the same folder.
  • Future<RecordSave> keepRecord(String path, String id, {required bool recorded}) — Keeps [id] as the record of the folder at [path], [recorded] or not, and answers once the store has it.
  • void removeRecentProject(String path)
  • void setLibraryPath(String? path) — Null returns to the app’s own library folder.
  • Future<bool> setWarnInsteadOfRefuse(bool warn) — Sets development mode’s switch (§9.5), from Settings → Development, and answers whether the store kept it.
  • void setAccountSignedIn(bool signedIn) — Set by the account’s state when a session starts or ends (§6.4: the hint is all the preferences file learns of the account).
  • void setDictationDevice(String? id, {String? label}) — The microphone dictation records from (§9.6); null returns to the system’s default.
  • void setDictationEngine(String? id) — The speech service dictation transcribes with (§9.6); null returns to the default.

lib/src/settings_tab_provider.dart

• class SettingsTab — Settings’ tabs, in the order they show (Software Specification §9.4).
  • static const general — The cards Settings shows in every build.
  • static const plugins — Plugins: what is installed, what each asks to use, the plug-ins’ own keys, and the preferred providers (§9.4).
  • static const models — Models: the default model of each kind of render, at Prototype and at Final, and the assistant’s text model (§9.4).
• variable final settingsTabProvider — Which of Settings’ tabs shows.
• class SettingsTabController — Holds the index of Settings’ tab showing; Settings’ bar and the dashboard set it.
  • void set(int tab) — Shows [tab], kept to the tabs there are.
  • void openPlugin(String tag) — Shows Plugins on the page of the plug-in [tag]: a door to a provider’s key (§6.7).
• variable final settingsPluginToOpenProvider — The plug-in whose page Settings → Plugins opens next; null once the tab has opened it.
• class SettingsPluginToOpen — Holds the plug-in a door asked Plugins to open, until the tab takes it.
  • void request(String tag) — Asks for [tag]’s page.
  • String? take() — The tag asked for, cleared as it is taken, so that a second door to the same plug-in opens it again.

lib/src/speech_providers.dart

• class SpeechProvider — A native speech service’s provider plug-in (§6.7): the platform dictation and the conversation speak to, and the plug-in whose key slot holds that platform’s key — fixed by tag and slot, never found by a name or b…
  • const SpeechProvider({required this.platform, required this.tag, required this.slot, required this.name})
  • final String platform — The catalogue’s platform the native session speaks to.
  • final String tag — The provider plug-in’s tag, whose page holds the key.
  • final String slot — The key slot the plug-in declares on [platform].
  • final String name — The provider’s name in a sentence and on a door.
  • String get keyId — <tag>:<slot>.
  • String get storeName — The credential store’s name of the key, the plug-in’s key card’s: from the fixed tag and slot, so it holds whether or not the plug-in is on now.
  • bool get ready — Whether a new session may read the key: the plug-in installed, allowed, on and runnable, declaring [slot] on [platform].
• variable const speechProviders — The two native speech services’ providers, defined here and nowhere else (§6.7).
• function SpeechProvider? speechProviderOf(String platform) — The provider of the speech service on [platform]; null for a platform no native service speaks to.

lib/src/sync_host.dart

• variable final syncHostProvider — The container’s [SyncHost]; null until one is made.
• class SyncHostSlot — Holds the container’s [SyncHost]; null until one is made.
  • void set(SyncHost host) — Records [host] as the container’s host.
• class SyncHost — Keeps the platform’s host for background transfers in step with the open film’s sync work (§6.14).
  • SyncHost(this._container, this._binding, this._service, {required BackgroundTransfers transfers, this._targetFor}) — Listens to [binding]’s notice, [service]’s views and the host’s events; nothing where [transfers] has no host.
  • ({int files, double progress})? counted(String projectKey) — The film’s moving transfers and their mean progress (unknown counting as zero); null where none is counted.
  • bool hasTarget() — Whether the open, ready film has a sync target, as the service’s own targetFor answers.
  • void lifecycleChanged(AppLifecycleState state) — Hears the app’s lifecycle before the binding does (§6.14): the first departure shows, resumed hides.

lib/src/sync_provider.dart

• function String? openFilmKey(ProviderContainer container) — The open, ready film’s key: null while no film is open, while one loads, and once it is closed (§6.14).
• class ContainerSyncEnvironment — Captures only the open, ready film whose target the application supplies.
  • ContainerSyncEnvironment(this._container, {required this._targetFor})
• function bool documentSendWaits(String projectKey, String path, {bool lifted = false}) — Whether the send of the document [path] in the film [projectKey] waits now (§6.14).
• variable final syncAppBindingProvider — The container’s [SyncAppBinding] once one is made: what the controller and the window’s exit ask (§6.14).
• class SyncAppBindingSlot — Holds the container’s [SyncAppBinding]; null until one is made.
  • void set(SyncAppBinding binding) — Records [binding] as the container’s binding.
• enum LeavingOutcome — How [SyncAppBinding.prepareLeaving] ended (§6.14).
  • values: complete, incomplete, refused
• class LeavingResult — What leaving a film did (§6.14): how it ended, its last stage, the document sends sent and pending, and a code.
  • const LeavingResult(this.outcome, this.stage, {this.sent = 0, this.pending = 0, this.code, this.ms = 0, this.local}) — Records one leaving’s end.
  • final LeavingOutcome outcome — How the leaving ended.
  • final String stage — The stage it ended at: settle, lift, reconcile or wait.
  • final int sent — The document sends in flight when the wait began that ended done.
  • final int pending — The film’s document sends neither done, failed nor cancelled at the end: they go at the next open.
  • final String? code — A safe code where the leaving did not complete: timeout, undone, notSynced, the sync’s reason (signInNeeded, or a target’s code: unreachable where the network failed, unavailable where the target is missin…
  • final int ms — The milliseconds the leaving took.
  • final List<String>? local — The film’s documents, by path, that differ from the sync ledger’s last agreement: what of the folder is not yet on the target, read locally after the drafts and again once a wait has ended (§6.14).
• variable final syncServiceProvider — The application-owned sync service; reading it activates nothing.
• variable final syncJobsProvider — The film’s jobs, subscribed before seeding and with equal snapshots suppressed.
• variable final syncStatusProvider — The film’s files against its cloud copy (§6.14): the service’s last comparison with its jobs laid over it, read again at each comparison and each change of the jobs, equal snapshots suppressed; null where none was made.
• function SyncService createApplicationSyncService(ProviderContainer container, { String? directory, required SyncTarget? Function(FilmProject) targetFor, Sy… — Constructs inert application sync ownership with bounded lanes and a two-second settle.
• class SyncAppBinding — Restores on opening, reconciles changes, refreshes arrival bursts and owns the bounded exit task.
  • SyncAppBinding(ProviderContainer container, SyncService service, {SyncEnvironment? environment}) — Listens for project changes and arrivals without restoring or reading a target at construction.
  • Stream<void> get backgroundPrepared — Fires when the current background preparation — settle, lift, reconcile — has ended, refused or with nothing to send included; never for a preparation a return to the foreground, a later departure or [close] made obso…
  • bool deferSend(String projectKey, String path) — Whether the send of the document [path] in the film [projectKey] waits now ([documentSendWaits]).
  • void release(String projectKey, String stem, String text, {required int ms}) — Lets the document [stem] of the film [projectKey] go while its form stays open (§6.14).
  • void dropRelease(String projectKey, String stem, String reason) — Ends the release of the document [stem] in [projectKey], if there is one, for [reason]: written before a later write of it through the controller, textChanged, filmChanged or closed (§6.14).
  • static bool moving(JobView job) — Whether [job] is moving: queued, working, or waiting for a retry — not parked; what the host counts too.
  • bool transferring(String projectKey) — Whether the open, ready, synced film [projectKey] has sync work queued, working or waiting for a retry (§6.14).
  • bool unsent(String projectKey) — Whether the open, ready, synced film [projectKey] has anything not yet on its target (§6.14): sync work moving, needing attention or waiting for any reason, or a form open on one of its files.
  • Future<void> accountReady() — The FilmOpen account reports a user, signed in or restored: the sync’s wait for a token is released and the open film reconciled; a film closed now reconciles when it next opens (§6.14).
  • void lifecycleChanged(AppLifecycleState state) — Hears the app’s lifecycle (§6.14).
  • Future<LeavingResult> prepareLeaving(String projectKey, {required Duration within}) — Prepares the film [projectKey] for being left — a switch, a close, the window’s exit — in one budget (§6.14).
  • void undoLeaving(String projectKey) — The person stayed: restores the deferral of the film [projectKey] that [prepareLeaving] lifted, and stops a preparation still under way from lifting it afterwards (§6.14).
  • List<JobView> pendingUploads(String projectKey) — The film’s uploads not yet done — queued, working, waiting to retry, held or needing a person — but neither done, failed nor cancelled: what of the person’s is still to go to the target (§6.14).
  • Future<void> close({Duration grace = const Duration(seconds: 10)}) — Cancels pending rereads, detaches every listener and closes the service once within its grace period.

lib/src/tree_builder.dart

• function ScriptOutline workingScriptOutline(FilmProject project, Author? viewer, {required String caller}) — The script as [viewer] works on it (Software Specification §5.12, §8): [scriptOutline] with the lists of the project file and of each unpinned folder read from the viewer’s assistant draft ([assistantDraftOf]) where t…
• function ({String name, String? detail}) epochNaming(String token, EpochDeclaration? declaration) — How a person sees the epoch [token] that [declaration] declares (§8.2).
• function String epochLine(AppLocalizations l10n, String token, EpochDeclaration? declaration) — [epochNaming] on one line, the year beside the label.
• function String scriptRowIdText(String written) — A script entry’s written text as part of a row’s identifier, %, / and # written as their codes: the one rule the tree and a folder’s contents name a script row by (§8.3).
• function List<String> scriptRowIds(String parentId, List<ScriptRow> rows) — The tree’s ids of [rows], the rows of one list under the row [parentId].
• function String propKindLabel(AppLocalizations l10n, String kind) — A prop kind’s name (A.3), or the token itself where A.3 does not name it.
• function String outfitConditionLabel(AppLocalizations l10n, String condition) — An outfit condition’s name (A.2), or the token itself where A.2 does not name it.
• function String groupName(FilmProject project, EntityGroup group, Author? viewer) — An entity’s name as a whole: the version in use’s, else the last-updated discarded version’s, else its tag.
• function ({String? action, String? entity, Map<String, Object?> logged}) chatOrigin(FilmProject project, SetRecord record, Author? viewer) — What a chat was asked (§8.2, §9.3): its action’s label through the record’s own assistant’s catalog, else its id; for a field’s or form section’s action, the entity’s name, else its id; and why each was or was not found.
• function int groupVersionCount(EntityGroup group) — How many versions an entity counts: the retained, or, where every version is discarded, every one.
• function String? lastNamed(Iterable<Entity> versions) — The name of the most recently updated of [versions] (a version without a readable updated counts as the oldest); null where there are none.
• class TreeBuilder — Builds the browsable tree of a project.
  • TreeBuilder(this.project, this.l10n, {this.viewer, ScriptOutline? outline, this.liveChats = const {}})
  • final FilmProject project
  • final AppLocalizations l10n
  • final Author? viewer — The current user, for author-first resolution of story references.
  • final Set<String> liveChats — The ids of the chats open in this app (assistantLiveChatsProvider): a chat record whose assistant_session is not among them is archived (§8.2).
  • List<TreeNode> build()

lib/src/tree_marks.dart

• class TreeMarks — The rows a person has marked, for one act that takes more than one, and the row a range is measured from (§8.1).
  • const TreeMarks({this.ids = const {}, this.anchor})
  • final Set<String> ids — The marked rows, by node id.
  • final String? anchor — The row a shift-click measures its range from: the last row clicked or control-clicked.
  • int get count — How many rows are marked.
  • bool get isMany — Whether more than one row is marked: a drag or Move to… of a marked row then carries them all.
  • bool holds(String id) — Whether [id] is marked.
• class TreeMarksNotifier — The one door of the marks: every change goes through it and is logged as tree.marks (§8.1).
  • void only(String id, {required String surface, Map<String, String> excluded = const {}}) — A plain click: [id] alone is marked, where it can move, and it becomes the anchor either way.
  • void toggle(String id, {required String surface, Map<String, String> excluded = const {}}) — A control- or command-click: [id] joins the marks, where it can move, or leaves them; it becomes the anchor.
  • void range(List<String> range, {required String surface, Map<String, String> excluded = const {}}) — A shift-click: every row of [range] that can move, in place of the marks.
  • void clear(String reason) — Nothing marked, for [reason]: after a move consumed them.
  • void consumed(TreeMarks taken) — The marks a move took, [taken], cleared as it settles where they are still the marks.
• variable final treeMarksProvider — The rows marked in the tree and on the Script page’s Contents (§8.1).

lib/src/tree_node.dart

• class TreeIcon — What a row’s icon stands for.
  • const TreeIcon()
• class EntityTreeIcon — The icon of an entity type (iconFor in the UI package).
  • const EntityTreeIcon(this.type)
  • final EntityType type
• class GlyphTreeIcon — A row that is not an entity: a grouping, or a record.
  • const GlyphTreeIcon(this.glyph)
  • final TreeGlyph glyph
• enum TreeGlyph — The grouping rows’ glyphs.
  • values: script, versions, shots, cues, epoch, record, other, unfiled, unread
• function bool rowHoldsContents(ScriptRow row) — Whether [row] is where a folder’s contents are drawn.
• class ScriptPlace — Where a row of the script sits: what its menu, a drag and an agent’s taps act on.
  • const ScriptPlace({this.parent, this.entry, this.occurrence = 0, this.index, this.siblings, this.container, this.name})
  • factory ScriptPlace.ofRow(ScriptRow row) — Where [row] sits: the list that holds it, the entry as written, and — for a folder that is drawn with what it holds — the version an Add goes into.
  • final Entity? parent — The file whose children lists the row — the project file in use, or the version of the folder drawn above it.
  • final String? entry — The entry as the parent writes it, and which of the equal entries it is.
  • final int occurrence
  • final int? index — Where the entry stands in [parent]’s list, and how long that list is — every entry of a list is a row, readable or not, but for those that name a folder or scene that is gone, which the list’s edits drop first (§8.5)…
  • final int? siblings
  • final Entity? container — The file an Add here goes into.
  • final String? name — What a message calls the row: the entity’s name, else the entry.
• class TreeNode — One row of the project tree.
  • const TreeNode({ required this.id, required this.label, required this.icon, this.detail, this.tooltip, this.shortName, this.place, this.selection,…
  • final String id — Unique within the tree; stable across rebuilds so expansion survives.
  • final String label
  • final String? detail — Secondary text shown after the label, muted.
  • final String? tooltip — Longer explanation shown on hover, when [detail] is not enough.
  • final String? shortName — The entity’s short name where the row shows it nowhere — a folder’s, whose detail is its kind — so that the filter still finds a row by name or tag, as its box says.
  • final ScriptPlace? place — Where the row sits in the script; null for every row outside it.
  • final TreeIcon icon
  • final Selection? selection — What clicking the row shows; null for rows that only group.
  • final List<TreeNode> children
  • final bool initiallyExpanded
  • final bool isOfficial — Starred for the official version, or the author holding it on an author row.
  • final bool isPick — Checked for the viewer’s pick, or the author holding it on an author row.
  • final bool isStalePick — Shown in red: the project made another version official after the viewer picked this one (§13.2).
  • final bool hasProblem — Marked with a warning: an unresolved or ambiguous reference.
  • final bool isDeleted — Struck through: the version the row shows is in the recycle bin (Project Specification §7).
  • bool get hasChildren
  • String get searchText — Text the filter matches against.
• class TreeModel — The built tree plus an index from selections to rows.
  • TreeModel(this.roots)
  • TreeModel.empty()
  • final List<TreeNode> roots
  • String? nodeIdFor(Selection selection) — The row that best represents [selection], or null when the tree has no row for it.
  • bool contains(String id) — Whether the tree has a row [id]: a row of the script changes its id when it changes its place.
  • TreeNode? nodeOf(String id) — The row [id] as the tree has it now, or null.
  • List<TreeNode> nodesInOrder(Set<String> ids) — The rows of [ids] the tree has, in the order it draws them, collected in one walk.
  • List<TreeNode> ancestorsOf(String id) — Every ancestor row of [id], outermost first; empty when absent.

lib/src/workflow_scope.dart

• class ScopedRow — One entity a Workflow focus gathers at one occurrence epoch, resolved as the viewer’s own page resolves it.
  • const ScopedRow({required this.type, required this.tag, required this.epoch, required this.entity, required this.fellBack, required this.owner, thi… — Records [tag] at [epoch] resolved to [entity].
  • final EntityType type — A character, an outfit, a location or a prop.
  • final String tag — The short name the scene wrote, or the group’s.
  • final String epoch — The epoch the row stands for: the inventory’s, the cast entry’s, location_epoch, a prop’s own, else the scene’s.
  • final Entity entity — The version in use for the viewer.
  • final bool fellBack — Whether [epoch] has no version and the project’s first epoch’s stands in.
  • final bool owner — Whether this is the first row that resolves to [entity].
  • final List<ScopedRow> outfits — A character’s outfits at [epoch], as the outfit list enumerates them, though [entity] fell back; else empty.
  • final bool inScene — False only on a row the inventory added that no scene uses ([sceneUsage]), which the tab marks.
• class ScopeLine — A line of the walk: a folder’s heading, or a scene with its blocks.
  • const ScopeLine({required this.stem, required this.name, required this.depth, required this.isScene, this.blocks = const []}) — Records [stem] at [depth].
  • final String stem — The full stem of the version drawn.
  • final String name — Its name.
  • final int depth — How deep it sits, as the Workflow tab indents it.
  • final bool isScene — Whether it is a scene; else a folder.
  • final List<String> blocks — A scene’s block ids in script order.
• class ScopeSkip — A row the walk left out, or a reference that does not resolve, and why — never guessed.
  • const ScopeSkip({required this.row, required this.parent, required this.reason, this.epoch}) — Records [row] in [parent] skipped for [reason].
  • final String row — The entry as written, or a reference as <prefix>_<tag>.
  • final String? parent — The full stem of the file it was read from; null where no list holds it.
  • final String reason — cycle, duplicate, unresolved or deleted for a row, and for the inventory’s library or alreadyShown.
  • final String? epoch — The epoch a reference was looked up at; null for a row.
• function Set<String> sceneUsage(FilmProject project, Author? viewer) — Every ch_<tag>@<epoch> and lo_<tag>@<epoch> the project’s scenes use for [viewer], whichever the focus.
• class WorkflowScope — What a Workflow focus gathers for one viewer: its scenes, what they use and the project’s other people and places.
  • factory WorkflowScope.of(FilmProject project, Entity focus, List<ScriptRow> rows, Author? viewer) — Gathers [focus] — the project file with the script’s [rows], a folder with its own outline’s, or a scene alone — for [viewer], logging workflow.scope.computing, each workflow.scope.skipped, `workflow.scope.fellBac…
  • final Entity focus — The project file, folder or scene gathered.
  • final List<ScopedRow> characters — One row per character and occurrence epoch, in first-appearance order, each with its outfits; then the inventory’s.
  • final List<ScopedRow> locations — One row per location and occurrence epoch; then the inventory’s.
  • final List<ScopedRow> props — One row per prop and occurrence epoch.
  • final List<ScopeLine> scenes — The walk’s lines in order: the focus where it is a folder or a scene, then what lies beneath it.
  • final List<ScopeSkip> skipped — What the walk left out and what did not resolve, in the order met.
• variable final workflowScopeProvider — The scope of the focus whose full stem is the argument, for the open project and the viewer.

lib/src/workflow_state.dart

• enum StepDone — What a workflow step’s checkbox shows (D1): done, not yet, or no checkbox at all.
  • values: done, notDone, noCheck
• class WorkflowDone — The answers to a workflow’s done checks for one project snapshot and one viewer (D1), counted once.
  • factory WorkflowDone.of(FilmProject project, ScriptOutline outline, {Author? viewer}) — Counts [project] as [outline] draws it for [viewer], logging workflow.done.counting, one workflow.done.skipped per row left out and workflow.done.counted with every count.
  • final FilmProject project — The project snapshot the counts were taken from.
  • final Entity? root — The project file whose children is the top of the script; its stem keys the project’s counts.
  • final Author? viewer — The viewer the counts resolved for; null for the format’s default reading.
  • StepDone check(Object? done, Entity focus) — Whether the step whose done is [done] — the workflow file’s JSON as parsed — is done on [focus].
• variable final workflowDoneProvider — The answers to the workflow’s done checks for the open project and the viewer; null while no project is loaded.
• typedef typedef WorkflowPreferences — The workflow’s two machine preferences: the chosen scriptwriting plug-in’s tag and the ceiling in USD a step’s run stops at; null for none.
• class WorkflowPreferencesController — Keeps the workflow’s two preferences on this computer: read once at build, each change the state at once and then written, the value staying for the session if the write fails.
  • static const pluginKey — The host’s PluginPreferences.preferred('script-writer'): the state reads and writes the host’s own key, through the same store, so that nothing in the host changes.
  • static const ceilingKey — The ceiling in USD, a number; absent for none.
  • Future<void> choosePlugin(String? tag) — Chooses the plug-in [tag] whose workflow the tabs show; null or empty is none, the key removed.
  • Future<void> setCeiling(double? usd) — Sets the ceiling a step’s run stops at to [usd]; null is none, the key removed.
• variable final workflowPreferencesProvider — The workflow’s chosen plug-in and ceiling, kept on this computer.

lib/src/write_problem_text.dart

• extension WriteProblemText — The sentence for a refused or failed write, wherever it is shown.
  • String writeProblemText(Object? error)

Internal

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

• lib/src/seam_slot.dart: SeamSlot