filmopen_sharing

A snapshot

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

How a film is shared: the sync target a film names — Google Drive by the folder id in its manifest, or a folder of this computer kept in its preferences — the Google account it needs, the Sharing card of Settings that starts, shows and stops it, and the new-project dialog’s cloud choice and director block. A feature package: it imports the sync, the Drive client, the state, the widgets and the words; the application imports it, and filmopen_tree for the new-project dialog.

Flutter. 12 files, 2,794 lines under lib/; 187 tests in 14 files. Barrel: lib/filmopen_sharing.dart.

Depends on

• filmopen_sync — uses FolderSyncTarget, NoSyncService, SyncLane, SyncTarget, SyncTargetException
• filmopen_jobs — uses JobAction, JobActionAck, JobPhase, JobView, describeJobError
• filmopen_drive — uses DriveAuth, DriveClient, DriveError, DriveException, DriveFile, DriveSyncTarget, DriveTrail
• filmopen_cloud — uses FilmOpenCloudTarget
• filmopen_state — uses AccountAccess, AccountAuthentication, AccountIdentity, AccountNames, AccountNamesStatus, AccountProjects, AccountProjectsRefused, AccountSnapshot, AccountSnapshots, KnownAccountBalance, ProjectRecord, RecordSave, Settings, accountNamesProvider, accountOpenerProvider, accountSnapshotProvider, folderDialogsAvailableProvider, incomingLinksProvider, kDefaultViewerHandle, kFilmOpenDomain, projectClosedProvider, projectProvider, settingsProvider, syncJobsProvider, syncServiceProvider
• filmopen_store — uses AppLog, LogLevel, ManifestRefused, NoManifestException, NoViewerException, ProjectFolderNotEmptyException, kManifestMaxBytes, verifiedManifest
• filmopen_format — uses FilmProject, ShortName, StaleFileException, SyncSettings, canonicalRootPath, newUsageId, projectKeyOf, projectManifestFileName
• filmopen_platform — uses IncomingLinks
• filmopen_ui — uses AppColors, SectionCard, ShortNameField, showMessage
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: flutter_riverpod, file_selector, url_launcher.

Used by

filmopen_app, 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/alias_dialog.dart

• function Future<AccountIdentity?> showAliasDialog(BuildContext context, {required bool primary}) — Claims a username for the account (§9.2): its primary where [primary], else an alias; answers the identity claimed, or null when cancelled.
• class AliasDialog — The alias dialog: a username box checked with the website as its text settles, and OK that claims it.
  • const AliasDialog({super.key, required this.primary, this.settle = const Duration(milliseconds: 500)}) — The dialog claiming the account’s primary where [primary], else an alias.
  • final bool primary — Whether the name claimed is the account’s primary: an account with no username yet.
  • final Duration settle — How long the text rests before it is checked.

lib/src/cloud_choice.dart

• enum CloudProvider — The clouds a new project can be synced to (§9.2): FilmOpen Cloud and Google Drive now, iCloud and Dropbox to come.
  • values: filmopen, drive, icloud, dropbox
• class AccountSnapshotBuilder — Rebuilds with the account’s public snapshot as it changes, a source installed meanwhile included (accountSnapshotProvider).
  • const AccountSnapshotBuilder({super.key, required this.builder}) — Builds [builder] with the current snapshot, and again after each change.
  • final Widget Function(BuildContext context, AccountSnapshot snapshot) builder — What is drawn for a snapshot.
• class CloudOptions — Which clouds can take a new project now, and why each other cannot (§9.2): read from the account and the settings, never guessed — a balance not known is not a zero.
  • const CloudOptions({required this.snapshot, required this.driveSignedIn, required this.driveConfigured}) — The options for [snapshot], with Google signed in on this machine where [driveSignedIn] and a Google client in the build where [driveConfigured].
  • final AccountSnapshot snapshot — The account’s public state.
  • final bool driveSignedIn — Whether this machine was last signed in to Google (Settings.driveSignedIn).
  • final bool driveConfigured — Whether the build has a Google client.
  • bool get signedIn — Whether the account is signed in.
  • bool enabled(CloudProvider provider) — Whether [provider] can take the project now.
  • List<CloudProvider> get available — The clouds that can take the project, in the order they are shown.
  • CloudProvider? selected(CloudProvider? picked) — The cloud in effect: [picked] where it can take the project, else the first that can; null where none can.
  • String? get filmopenReason — Why FilmOpen Cloud cannot be chosen, as a code — signedOut, balanceUnknown, noBalance — or null.
  • String? get driveReason — Why Google Drive cannot be chosen, as a code — unconfigured, signedOut — or null.
  • String? filmopenReasonText(AppLocalizations l10n) — FilmOpen Cloud’s reason as a sentence: the first radio’s, which Create says where no cloud can take the project; null where it can.
• function Future<String?> shareNewProjectOnDrive(SharingModel model, FilmProject project) — Shares a new project on Google Drive and answers why it is not shared: the Sharing model’s notice, notShared where the share ended with neither a notice nor Drive in the manifest, or null where it is shared (§9.2).
• class CloudChoice — The new-project dialog’s cloud block (§9.2): Sync this project to the cloud…? and, checked, the four clouds, each disabled with what would enable it under it.
  • const CloudChoice({ super.key, required this.snapshot, required this.sync, required this.picked, required this.onChanged, this.model, this.launch, }) — The block for [snapshot], over the application’s [SharingModel] or [model] where a test passes one.
  • final AccountSnapshot snapshot — The account’s public state, which the dialog follows ([AccountSnapshotBuilder]).
  • final bool sync — Whether the box is checked.
  • final CloudProvider? picked — The cloud the person picked, null until they pick one.
  • final void Function(bool sync, CloudProvider? picked) onChanged — Called with the box and the pick as the person changes either.
  • final SharingModel? model — The Sharing model whose Google sign-in Drive’s button starts.
  • final Future<bool> Function(Uri uri)? launch — Opens a page in the browser — url_launcher’s by default, a test’s own otherwise.

lib/src/director_choice.dart

• enum DirectorSource — Where the director came from: the username box, or the account’s pulldown.
  • values: field, pulldown
• typedef typedef AddAlias — Claims a new username for the account, the primary where [primary]; answers the identity, or null when cancelled.
• class DirectorChoice — The new-project dialog’s director block (§9.2): Director role assigned to: with a username box signed out, and signed in the account’s usernames ([AccountUsernameChoice]), the last item adding another as an alias.
  • const DirectorChoice({ super.key, required this.snapshot, required this.value, required this.onChanged, this.addAlias, }) — The block for [snapshot], opening on [value].
  • final AccountSnapshot snapshot — The account’s public state, which the dialog follows.
  • final String value — The director in effect: a valid username.
  • final void Function(String username, DirectorSource source) onChanged — Called with a valid username as the person chooses one; never with an invalid one.
  • final AddAlias? addAlias — Opens the alias dialog.
• class AccountUsernameChoice — Signed in, the username chosen from the account’s names, never typed (§6.6, §9.2, §9.4): a pull-down of the names read ([accountNamesProvider]), the last item claiming another where [addAlias] is given.
  • const AccountUsernameChoice({ super.key, required this.value, required this.onChosen, required this.identifier, required this.modeEvent, required t… — The choice showing [value], which [onChosen] hears of; [identifier] names it to an agent.
  • final String value — The username in effect, shown as it is even where it is not one of the names.
  • final void Function(String username) onChosen — Called with the username a person chose, or claimed.
  • final String identifier — The semantics identifier of the control; its retry and claim are <identifier>.retry and <identifier>.alias.
  • final String modeEvent — The event that logs which presentation is shown, by its mode alone.
  • final String aliasEvent — The event that logs a claim: <aliasEvent>.open, then <aliasEvent> with its outcome.
  • final AddAlias? addAlias — Opens the claim dialog; null offers no claim.

lib/src/drive_account.dart

• class DriveAccount — The Google account of this machine as the sharing needs it: signed in or not, sign in, sign out.
  • DriveAccount({DriveAuth? auth}) — An account signing in through [auth], or through a DriveAuth of its own over the app’s link door.
  • static void withhold() — Withholds Google Drive from this process for good, before any account is made: an agent build’s entrypoint calls it, so that no Drive client reaches the person’s credential store (DriveAuth.withhold, §6.10).
  • final DriveAuth auth — The sign-in the account goes through.
  • void bind(Ref ref) — Keeps the account’s hint, which the card draws, in [ref]’s settings (driveSignedIn) from now on.
  • bool get signedInBefore — What the card draws: the preference the last sign-in or sign-out left, never a read of the credential store.
  • bool get isConfigured — Whether this build has a Google client at all; without one the card says so and offers no sign-in.
  • Future<void> signIn({Future<void>? abandon}) — Signs this machine in through Google’s consent page in the browser, and sets the preference where it succeeds.
  • Future<void> signOut() — Forgets the tokens, the Drive folders’ lookups and the preference; the files at Drive stay.
• variable final driveAccountProvider — The one DriveAccount of the application, made on first read and bound to the settings.

lib/src/sharing_card.dart

• class FilmOpenSharingCard — The Sharing card on Settings → General (§9.4): the open film’s sharing, its two ways to start, and its stop.
  • const FilmOpenSharingCard({super.key, SharingModel? model}) — The card, over the application’s [SharingModel], or over [model] where a test passes one over stand-ins.

lib/src/sharing_model.dart

• class SharingState — What the card shows of the open film’s sharing, read from its manifest and this machine’s folder for it.
  • const SharingState.notShared() — The film is not shared.
  • const SharingState.onDrive(String this.name) — The film is shared on Google Drive, in FilmOpen/<name>.
  • const SharingState.toFolder(this.path) — The film is shared to a folder: [path] on this machine, or null where this machine has chosen none.
  • const SharingState.onFilmOpen(String this.name) — The film is shared on FilmOpen Cloud, as <username>/<tag>.
  • final String? target — drive, folder, filmopen, or null for a film that is not shared.
  • final String? name — The Drive folder’s name, for a film shared on Drive; the <username>/<tag> of a film on FilmOpen Cloud.
  • final String? path — The folder of this machine the film is shared to, for a film shared to a folder this machine has chosen.
  • bool get isShared — Whether the film names a target.
  • bool get folderNotChosen — Whether the film is shared to a folder and this machine has no path for it.
• enum RecordResult — What became of recording a project on the account (§6.6, The account’s projects).
  • values: created, replayed, updated, refused, unreachable, notSaved, markerNotSaved
• class RecordOutcome — A record’s outcome and its safe code: the result’s name, or the refusal’s code.
  • const RecordOutcome(this.result, {this.refusal}) — The outcome [result], with [refusal] for a refusal.
  • final RecordResult result — What became of the record.
  • final String? refusal — A refusal’s code: noFolder, manifestMissing, identityMismatch, recordMissing, readFailed, failed, or the account’s own.
  • String get code — The safe code: the refusal’s, else the result’s name.
  • bool get recorded — Whether the account holds the record and this device knows it.
• enum CloudShareStage — The stage a share on FilmOpen Cloud stopped at.
  • values: identity, record, restart, manifest
• class CloudShareOutcome — What a share on FilmOpen Cloud came to: ready, or the stage it stopped at and its safe code.
  • const CloudShareOutcome.ready() — The film is recorded and sync names FilmOpen Cloud.
  • const CloudShareOutcome.failed(CloudShareStage this.stage, String this.code) — The share stopped at [stage], for [code]; nothing after it happened.
  • final CloudShareStage? stage — The stage it stopped at; null where it is ready.
  • final String? code — Why it stopped; null where it is ready.
  • bool get ready — Whether the share went through.
• class RecordPullFailure — Why opening a recorded project’s manifest stopped: the [stage] (lookup, manifest, bootstrap) and a safe [code] — a refusal’s own, or, where [unexpected], the failure’s type.
  • const RecordPullFailure(this.stage, this.code, {this.unexpected = false}) — A stop at [stage] for [code].
  • final String stage — Where it stopped.
  • final String code — Why: unsupportedProvider, driveUnconfigured, signInRefused, driveFolderAbsent, badIdentity, a target’s code, manifestLength, manifestMd5, manifestNotText, notEmpty, badTag; a type where [unexpected].
  • final bool unexpected — Whether nothing foresaw the failure: [code] is then its type.
• typedef typedef CloudTargetFor — Makes the FilmOpen Cloud target for <username>/<tag> [identity], which asks [accessToken] inside its operations.
• class SharingModel — The Sharing card’s state and its actions on the open film, with the Google sign-in they need.
  • SharingModel(this.ref, {required this.account, this.authTimeout = const Duration(seconds: 30), this.cloudTarget = _cloudTargetFor}) — The model over [account], reading the open film, the settings and the sync service through [ref].
  • final Ref ref — What the model reads the open film, the settings and the sync service through.
  • final DriveAccount account — The Google account the model signs in and out.
  • final Duration authTimeout — How long the model waits for the account to give it a client before it counts Google as unreachable.
  • final CloudTargetFor cloudTarget — How a recorded project’s FilmOpen Cloud target is made ([pullManifest]): the real one at kFilmOpenDomain, or a test’s over a stand-in.
  • Stream<String> get notices — Every notice as its code, as it is raised.
  • String? get notice — The last refusal or failure, as its code, until the next gesture or sign-in; null where there is none.
  • String? noticeOn(FilmProject? project) — The notice to draw on [project]’s card: [notice] where it is about that film or about no film, else none.
  • RecordOutcome? get recordOutcome — The last record’s outcome, until the next gesture; null where there is none.
  • RecordOutcome? recordOutcomeOn(FilmProject? project) — [recordOutcome] where it is about [project], else null: a record of one film never stands under another’s.
  • bool get busy — Whether a gesture is under way or queued: the card’s buttons wait for it.
  • bool get waitingForBrowser — Whether a sign-in is under way, which [cancelSignIn] stops waiting for.
  • SharingState stateOf(FilmProject project, Settings settings) — Reads the film’s manifest (sync) and this machine’s folder for the film.
  • ({String provider, String location}) recordPlaceOf(FilmProject project, Settings settings) — Where the account records [project]: its folder’s path where it is not shared or shared to a folder, FilmOpen/<tag> on Drive, <username>/<tag> on FilmOpen Cloud.
  • Future<RecordOutcome> recordProject(FilmProject project, {required String username, required String provider, required String location}) — Records [project] on the account as directed by [username], at [location] of [provider] (§6.6), queued behind the gestures before it.
  • Future<bool> signIn() — Opens Google’s consent page in the browser and answers whether this machine is signed in when it is done.
  • Future<bool> ensureSignedIn() — Answers whether this machine holds a sign-in Google takes, opening the consent page only where it must.
  • void cancelSignIn() — Stops waiting for the sign-in under way, which answers false at once.
  • Future<void> signOut() — Forgets this machine’s Google sign-in, queued behind the gestures before it.
  • Future<void> shareOnDrive(FilmProject project) — Shares the film on Google Drive, in FilmOpen/<tag> of My Drive.
  • Future<CloudShareOutcome> shareOnFilmOpenCloud(FilmProject project) — Shares the film on FilmOpen Cloud, as <username>/<tag>, the username the viewer’s.
  • Future<void> shareToFolder(FilmProject project, String path) — Shares the film to the folder [path] of this machine.
  • Future<void> stopSharing(FilmProject project) — Stops sharing the film: removes sync from its manifest and this machine’s folder for it.
  • Future<DriveFile?> findDriveFolder(String tag) — The Drive folder FilmOpen/<tag> of My Drive, or null where either folder is absent; never makes one.
  • Future<String> driveFolderOf(ProjectRecord record) — The id of [record]’s Drive folder, after the sign-in Drive needs: FilmOpen/<tag> found by [findDriveFolder].
  • Future<String> pullManifest(ProjectRecord record, String parentPath, {String? driveFolderId}) — Makes <parentPath>/<tag> for [record], a project the account records on FilmOpen Cloud or Drive, from the manifest its target holds, and answers the folder’s path; the ordinary sync fills it once it is opened (§9.4).
• variable final sharingModelProvider — The application’s one [SharingModel], over its Google account: made on first read, and ended with the container.

lib/src/sharing_targets.dart

• function SyncTarget? sharingTargetFor(FilmProject project, { required DriveAuth auth, required String? Function(String projectKey) folderPathFor, required F… — The sync target the film’s manifest names, or null where it names none this machine can reach.

Internal

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

• lib/src/folder_rule.dart: folderRefusal, canTakeFolder
• lib/src/full_path.dart
• lib/src/full_path_io.dart: isFullPath, resolvedFolder
• lib/src/full_path_stub.dart: isFullPath, resolvedFolder