filmopen_store

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

Where a project’s files come from and how they are written, as pure Dart: the folder source (directory_source*.dart, dart:io behind a stub), the loader, the writer (project_writer.dart) with its refusals, the creator and the template, Guards (development mode’s policy), the log (app_log.dart, log_file*.dart) and the library install.

pure Dart. 27 files, 4,740 lines under lib/; 568 tests in 50 files. Barrel: lib/filmopen_store.dart.

Depends on

filmopen_format — uses AllocatedId, AllocationInventory, Author, BatchStem, ChildEntry, Commentary, CommentaryStem, DuplicateKeyException, Entity, EntityGroup, EntityOrigin, EntityType, EntityVersions, EpochDeclaration, FileMedia, FileNameParser, FilmProject, MediaLocation, NotJsonObjectException, OfficialPointer, OfficialStem, ProjectArea, ProjectManifest, ProjectSource, ProjectWarning, PromptPath, PromptState, RenderBatch, SetRecord, ShortName and 59 more
filmopen_test_support (dev) — uses nothing by name the digest could see

Third-party: crypto.

Used by

filmopen_account, filmopen_app, filmopen_assistant_ui, filmopen_automation, filmopen_browser, filmopen_cloud, filmopen_compare, filmopen_device, filmopen_dictation, filmopen_drive, filmopen_engine, filmopen_engine_bench, filmopen_engine_mlt, filmopen_engine_mpv, filmopen_exchange, filmopen_fdx, filmopen_forms, filmopen_insertion, filmopen_insertion_ui, filmopen_jobs_ui, filmopen_keys, filmopen_machine, filmopen_media_ui, filmopen_picker, filmopen_platform, filmopen_plugin_host, filmopen_plugins_ui, filmopen_prompt_ui, filmopen_recorder, filmopen_relay, filmopen_render_ui, filmopen_sharing, filmopen_state, filmopen_support, filmopen_test_support, filmopen_timeline, 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/app_log.dart`

enum LogLevel — Verbosity, least to most.
- values: error, warning, info, debug, trace
- static LogLevel? fromName(String name)
class LogEntry — One line of the log.
- LogEntry(this.level, this.event, {this.data = const {}, this.error, this.stackTrace, DateTime? time})
- final DateTime time
- final LogLevel level
- final String event — A stable dotted name, e.g. project.opened, render.failed.
- final Map<String, Object?> data — Structured detail.
- final Object? error
- final StackTrace? stackTrace
- Map<String, Object?> toJson()
- String toLine() — The JSON line, without its newline.
class LogSink — Where log lines go.
- void write(LogEntry entry)
- Future<void> close() — Flushes and releases resources.
class MemoryLogSink — Keeps entries in memory, for tests.
- final List<LogEntry> entries
class LineLogSink — Hands each line to a callback: the console, a test.
- const LineLogSink(this.onLine)
- final void Function(String line) onLine
class AppLog — The application log.
- AppLog({this.threshold = LogLevel.info})
- static final AppLog instance
- static String digestOf(String value) — The first 12 hexadecimal characters of the SHA-256 of [value]’s UTF-8: a short, stable identifier made from a value.
- LogLevel threshold — Entries above this level are dropped before reaching any sink.
- bool thresholdPinned — True when the environment (FILMOPEN_LOG_LEVEL) fixed the threshold.
- void pinThreshold(LogLevel level) — Fixes [threshold] for the run; see [thresholdPinned].
- void applyVerbose(bool verbose) — Applies the verbose logs setting unless the environment pinned a level.
- void forceVerbose(bool on, {required String reason}) — Verbose while a recording runs, [on] at its start and off at its end, whatever the setting says (§6.8): in memory only, so the setting and the preferences are never touched and a crash leaves nothing to undo.
- String? filePath — Where the file sink writes, when one is attached; shown in Settings.
- List<LogSink> get sinks
- void addSink(LogSink sink)
- void removeSink(LogSink sink)
- bool isEnabled(LogLevel level)
- void log(LogLevel level, String event, {Map<String, Object?> data = const {}, Object? error, StackTrace? stackTrace})
- void error(String event, {Map<String, Object?> data = const {}, Object? error, StackTrace? stackTrace})
- void warning(String event, {Map<String, Object?> data = const {}, Object? error})
- void info(String event, {Map<String, Object?> data = const {}})
- void debug(String event, {Map<String, Object?> data = const {}})
- void trace(String event, {Map<String, Object?> data = const {}})
- Future<T> timed<T>(String event, Future<T> Function() body, {LogLevel level = LogLevel.debug, Map<String, Object?> data = const {}}) — Runs [body], logging how long it took.
- Future<void> close()

`lib/src/guards.dart`

enum GuardRule — A refusal the development switch governs.
- values: notYourFile, notDirector, libraryFile
class Guards — The policy the writer consults before refusing a [GuardRule].
- const Guards({this.warnOnly = false})
- static const Guards enforce — Every guard refuses: a release build, and any caller that did not ask.
- static const Guards warn — Development mode: a governed guard warns instead of refusing.
- final bool warnOnly
- void check(GuardRule rule, Exception Function() refusal, {Map<String, Object?> data = const {}}) — Throws what [refusal] makes when enforcing, after logging guard.refused; in development mode lets it through.
- void report(Iterable<GuardRule> rules, {Map<String, Object?> data = const {}}) — Logs guard.overridden for each rule a write went ahead in spite of, with [data] — the viewer and the file.

`lib/src/imported_project.dart`

function Future<VersionStem> writeImportedProject(ProjectSource target, { required List<Map<String, dynamic>> documents, required Author author, }) — Writes a complete imported film to an empty source under one author (§18.3).

`lib/src/library_install_stub.dart`

function Future<int> installLibraryIfEmpty(String directory, ProjectSource seed) — No files on this platform: the bundled copy is read in place.

`lib/src/log_file_stub.dart`

function LogSink? openFileLogSink(String path) — No files on this platform: the console sink is the only one.

`lib/src/project_bootstrap.dart`

variable const int kManifestMaxBytes — The largest manifest a bootstrap takes: a manifest is a few lines, and a body past this is no manifest.
class ManifestRefused — A manifest refused before any folder is made, by its code: manifestLength, manifestMd5 or manifestNotText.
- const ManifestRefused(this.code) — A refusal under [code].
- final String code — Why the manifest was refused.
function String verifiedManifest(List<int> bytes, {required int length, String? md5}) — The manifest’s text, once [bytes] are as long as [length] said and, where the target gave one, hash to [md5].

`lib/src/project_creator_stub.dart`

variable const bool canCreateProjects — Whether this platform can create project folders on disk.
function Future<String> copyImportedProjectTo({required String parentPath, required String prefix, required ProjectSource source}) — Imports cannot be persisted as folders on this platform.
class ProjectFolderNotEmptyException
- const ProjectFolderNotEmptyException(this.path)
- final String path
class ProjectFolderIsLinkException
- const ProjectFolderIsLinkException(this.path)
- final String path
class NotAProjectFolderException
- const NotAProjectFolderException(this.path)
- final String path
function Future<String> createProject({ required String parentPath, required String tag, required Author author, String? name, required String epochLabel, r…
function Future<String> copyProjectTo({ required String parentPath, required String folder, required ProjectSource source, })
function Future<void> deleteProjectFolder(String path)
function bool isDeletableProjectFolder(String path)
function bool sameFolderPath(String a, String b)

`lib/src/project_loader.dart`

class HeldLibrary — The shared library as read once per library folder: its listing and its documents’ text.
- HeldLibrary(this.source) — Holds nothing of [source] yet: the first read of a film lists and reads it.
- final ProjectSource source — The library folder this holds.
- List<String>? paths — The library’s listing; null until it listed.
- final Map<String, String> texts — Each document’s text by its path.
function Map<String, String> heldTextsOf(FilmProject project) — The text of every document of [project]’s own folder that its index holds, by path.
class ProjectLoader — Builds the FilmProject index from source filenames and JSON documents (§4.2, §5.4).
- const ProjectLoader()
- static const readsAtOnce — How many documents a load reads at once (§7.5).
- Future<FilmProject> load(ProjectSource source, {ProjectSource? library, Map<String, String>? held, Set<String> Function()? skip, HeldLibrary? heldL… — Loads a project and optional library, logging its folders, paths and warnings’ values as they are (§6.2).
- FilmProject overlay(FilmProject published, List<RecordedWrite> landed, {required List<String> listing, HeldLibrary? library}) — [published] with [landed] laid over it, built from the text it holds and [listing], reading nothing (§7.5).

`lib/src/project_template.dart`

variable const JsonEncoder projectJsonEncoder — Two-space indentation and a final newline, as §18.1 asks of writers.
function String encodeProjectJson(Object? json)
variable const String firstSceneTag — The short name of the scene a new project starts with.
variable const Set<String> firstSceneKeys — The keys [writeNewProject] writes into the first scene: a scene with these and no other is as it was made.
function bool isUntouchedFirstScene(Entity scene) — Whether [scene] is the first scene a new project is made with, untouched: [firstSceneTag], v1, exactly [firstSceneKeys], and never saved since (created equal to updated).
function Future<String> writeNewProject(ProjectSource target, { required String tag, required Author author, String? name, required String epochLabel, requi… — Writes the root manifest and the scene and project documents in data/ (§4.1).
function String rfc3339Now([DateTime? now]) — RFC 3339 UTC to the second (§7 created / updated), without Dart’s microseconds.

`lib/src/project_writer.dart`

class NoManifestException — A manifest write requires an existing project manifest (§4.4).
- const NoManifestException()
class NoSelectedProjectException — Declaring an epoch requires the project version in use for the viewer (§8.2).
- const NoSelectedProjectException() — Refuses a missing project file or an unresolved choice between project versions.
class EpochSourceUnavailableException — Creating at a missing epoch requires a resolved version at the chosen source epoch.
- const EpochSourceUnavailableException(this.groupKey, this.epoch) — Refuses a missing group, source epoch or viewer resolution without choosing another source.
- final String groupKey — The canonical entity group whose source could not be resolved.
- final String epoch — The explicitly chosen source epoch.
class OutfitParentUnavailableException — A new outfit requires an existing character group in the project or library.
- const OutfitParentUnavailableException(this.character) — Refuses an absent character without copying or creating its parent.
- final String character — The complete character tag whose group is missing.
class EpochDeclaredPickFailedException — The declared epoch exists in a new project fork, but selecting that fork failed.
- const EpochDeclaredPickFailedException(this.epoch, this.stem) — Reports partial completion without undoing the fork or allocating another epoch.
- final String epoch — The allocated token already written into the fork’s declarations.
- final VersionStem stem — The existing project fork the caller can recover after refreshing.
class ProjectReadOnlyException — The project’s files cannot be written (bundled assets).
- const ProjectReadOnlyException(this.label)
- final String label
class NotYourFileException — The file belongs to another author; edit a fork instead (§17 rule 2).
- const NotYourFileException(this.stem, this.owner, this.viewer)
- final String stem
- final Author owner — Who the file belongs to.
- final Author? viewer
class NotYourTakeException — A take another author made, whose file is theirs (§9.0): its entry’s flag stands, its file stays.
- const NotYourTakeException(super.stem, super.owner, super.viewer)
class TakeStillNamedException — A take whose file a live entry of another document still names (§9.0): only the entry’s flag stands.
- const TakeStillNamedException(this.reference, this.documents)
- final String reference — The take’s stem.
- final List<String> documents — The stems of the documents whose live entries name it.
class NoViewerException — Writing without a viewer handle: there is no author to write as.
- const NoViewerException()
class NotDirectorException — Only a director of the project writes official pointers (§8.3, §13.2).
- const NotDirectorException(this.viewer)
- final Author? viewer
class IdentityChangedException — A save tried to change what names the file (§7): filmopen, type, tag, epoch, author or v.
- const IdentityChangedException(this.key)
- final String key
class NextEpochLoweredException — A save refused because it would lower, drop or spoil a project file’s next_epoch.
- const NextEpochLoweredException(this.floor) — The refusal, naming the [floor] the file holds.
- final num floor — The floor the file holds.
class EntityExistsException — A new entity was asked for under a tag its type already has.
- const EntityExistsException(this.groupKey)
- final String groupKey — <type>_<tag>, e.g. ch_main-hero.
class DiscardOfficialException — A version official names, or the project file of record, was asked to be discarded (§6.1, §4.1): the director moves or clears the star first.
- const DiscardOfficialException(this.stem)
- final String stem — The version’s stem.
class PluginOutputException — What a plug-in’s entity hook returned cannot be written (§14.4).
- const PluginOutputException(this.code)
- final String code
class PluginRun — A plug-in’s run, as its files record it (Project Specification §12.4, §14.4).
- const PluginRun({required this.tag, required this.stem, required this.hook, this.settings, this.item = const {}})
- final String tag
- final String stem
- final String hook
- final Map<String, Object?>? settings — The project-scoped settings the run had, for an entity hook: its batch records them, empty where it had none (§12.4).
- final Map<String, Object?> item — What a render’s record says it was asked (§12.2): its request, as the application prepared it, and from the plug-in’s answer stack, seed_applied: false, metadata and metadata_refused, which the record ke…
- Author runner(Author viewer) — The handle the run’s files are written under (§5.6, §14.4).
variable const List<String> identityKeys — The header fields that must equal the filename’s (§7).
enum ContentProblem — What a file must say to be worth writing (§7, §8.2, §18.3).
- values: nameRequired, versionLabelTooLong, epochsRequired, childrenNotAList, folderIntoItself, childListedTwice
class ForkSourceUnreadableException — A fork’s source could not be read to check it against the text it was read as; the fork was not written.
- const ForkSourceUnreadableException(super.path)
class InvalidContentException
- const InvalidContentException(this.problem)
- final ContentProblem problem
function void validateContent(EntityType type, Map<String, dynamic> json) — Refuses content the format requires otherwise.
class RecordedWrite — One write a [ProjectWriter] made or is making: the source it went to, the path, and the text, null for a deletion.
- final ProjectSource root — The source written: the project’s, or the library’s for a development-mode save of a library entity (§9.5).
- final String path — The path within [root].
- final String? text — What the write put there; null where it deleted the file.
- bool landed — Whether the source has answered the write; until then it is in flight.
class WriteRecord — What the app is writing and has written since the index last took it (§7.5).
- RecordedWrite begin(ProjectSource root, String path, String? text) — Enters a write of [text] (null: a deletion) at [path] in [root], in flight.
- void land(RecordedWrite write) — Marks [write] landed: the source answered it.
- void drop(RecordedWrite write, {bool stale = false}) — Removes [write], refused or failed; [stale] keeps its path for the next publication to read again.
- void markStale(ProjectSource root, String path) — Keeps [path] in [root], which a check found changed since it was read, for the next publication to read again.
- List<RecordedWrite> takeLanded([Iterable<ProjectSource>? roots]) — The landed writes in the order they were entered, removed from the record; those in flight stay.
- List<RecordedWrite> landedOf(Iterable<ProjectSource> roots) — The landed writes of [roots] in the order they were entered, left in the record: what a decision lays over the published index (§7.5).
- void release(List<RecordedWrite> writes) — Removes [writes], which a publication has laid into the index it published.
- List<(ProjectSource, String)> takeStale() — The paths stale refusals named since the last call, removed from the record.
- bool hasNews([Iterable<ProjectSource>? roots]) — Whether a publication has anything to take: a landed write or a stale path, of [roots] where given.
- Set<String> pathsOf(ProjectSource root) — The paths of [root] the record names, landed or in flight: a re-derivation does not read them.
- String? landedText(ProjectSource root, String path) — The text of the last landed write at [path] in [root], which the index may not hold yet.
- RecordedWrite? latest(ProjectSource root, String path) — The last write entered for [path] in [root], landed or in flight; null where the record names none.
class ProjectWriter — Writes guarded project documents through the source of an immutable project snapshot.
- ProjectWriter(this.project, {this.guards = Guards.enforce, this.record})
- final FilmProject project
- final WriteRecord? record — Where each write is entered before the source is asked, for the index to take (§7.5).
- Map<String, dynamic>? get written — The document this writer’s last save, create or fork wrote, as written; null before one landed.
- final Guards guards — Whether the rules about who may write warn instead of refusing (development mode, §9.5).
- Future<void> updateManifest(Map<String, Object?> Function(Map<String, Object?> json) change, {required Author? viewer}) — Changes the manifest as the viewer, against the text the index read, refusing a concurrent edit (§6.1).
- static const notContent — What a file holds beside its content (§7): a change to these alone does not move updated.
- static const blockNotContent — What a block holds beside its content (§10.3): its takes, the seconds the scene’s output gives it, its own time.
- Future<Entity> saveEntity(Entity entity, Map<String, dynamic> json, {required Author? viewer}) — Replaces the content of [entity]’s file with [json], setting updated where the content changed (§7).
- void checkSave(Entity entity, Map<String, dynamic> json, {required Author? viewer}) — Whether [saveEntity] would refuse [json] as the new content of [entity].
- Future<VersionStem> fork(Entity entity, {required Author? viewer, Map<String, dynamic>? content, String? draftLabel}) — Copies [entity] as the viewer’s own next version (§13.1), holding [content] where given, and returns its stem.
- Future<String> declareEpoch(String label, {int? year, required Author? viewer}) — Appends an allocated epoch to the viewer’s project version in use and returns its token (§8.2).
- Future<String> relabelEpoch(String tag, String label, {int? year, required Author? viewer}) — Gives the declared epoch [tag] of the viewer’s project version in use a new label and year, and returns its token.
- Future<VersionStem> createAtEpoch(EntityGroup group, String targetEpoch, {required String sourceEpoch, required Author? viewer, bool clear = false,… — Copies a character or location’s exact resolved source into a declared missing epoch as the viewer’s v1.
- Future<VersionStem> createOutfit(String character, String epoch, String name, {required Author? viewer, String? draftLabel}) — Creates a named outfit under an allocated owner identity for an existing character (§9.2).
- Future<VersionStem> createEntity({ required EntityType type, required String tag, String? epoch, required String name, String? kind, required Autho… — Writes a new entity as the viewer’s first version (§9, §10, §13.1).
- Future<List<String>> writePluginRun({ required PluginRun run, required List<Entity> sources, required List<Map<String, dynamic>> outputs, required… — Writes what a plug-in’s entity hook returned (Project Specification §14.4, §12.4, §5.6).
- static const renderRequestRequired — The members a render record’s request must hold (§12.2); the others are written where known.
- static const renderRequestOptional — The members a render record’s request may hold beside [renderRequestRequired].
- Future<bool> setDiscarded(Entity entity, {required bool discarded, required Author? viewer}) — Sets [entity] aside with discarded, or brings it back by removing the key (Project Specification §7, §6.1).
- Future<SetRecord> writeSet(SetRecord record, {required Author? viewer}) — Writes a pending set’s record — a comp, an assistant session or a render queue (Project Specification §12.7).
- Future<RenderBatch> writeImportBatch({ required BatchStem stem, required List<Map<String, dynamic>> items, required Author? viewer, Map<String, dyn… — Writes the record of one import action, or of one render (§12.2, §12.3).
- ({String choice, bool landed})? inUseRecorded(Entity entity, {required Author? viewer}) — The recorded choice, in flight or landed and unpublished, that makes [entity] the version in use, or null.
- Future<void> setOfficial(Entity entity, {required Author? viewer}) — Writes the official pointer for [entity]’s versions key (§13.2) naming it, with set_by and set_at.
- Future<void> clearOfficial(Entity entity, {required Author? viewer}) — Removes the official pointer for [entity]’s versions key, so the project has no chosen version there.
- Future<void> setPick(EntityVersions versions, {required Author? viewer, Entity? entity, bool trackOfficial = false}) — Records the viewer’s pick at [versions]’ epoch (§13.4).
- Future<bool> visit(Entity entity, {required Author? viewer, DateTime? now}) — Records when the viewer last had [entity]’s media on screen (§13.4 visited): [now], or this second.
- Future<bool> deleteTake(String reference, {required Author? viewer}) — Deletes the file of the take [reference] names, and its thumbnail (§9.0).

`lib/src/usage_log.dart`

class UsageLogUnavailable — A usage log that could not do what was asked, with a code.
- const UsageLogUnavailable(this.code)
- final String code
class UsageReading — What a reading of the log found (§6.7, Reading).
- const UsageReading({this.records = const [], this.skippedChains = const {}, this.complete = true})
- final List<UsageRecord> records — Every record read, in file and line order.
- final Set<String> skippedChains — The chains holding a record of a version this reader does not know, left out whole.
- final bool complete — False when a month file could not be read, so that a total can say it may be short.
- List<UsageChain> get chains — The calls read.
- static void addLines(String file, Iterable<String> lines, { required List<UsageRecord> records, required Set<String> skippedChains, required Set<St… — Reads the [lines] of the month file [file] into [records] and [skippedChains].
class UsageLog — Where usage records go (§6.7).
- const UsageLog()
- static UsageLog current — The log in use.
- static void install(UsageLog log) — Makes [log] the one in use.
- bool get isAvailable — Whether records can be written at all.
- Future<String> deviceId() — The id in the usage folder’s device.json, which is made on first use.
- Future<void> append(UsageRecord record) — Appends [record], or throws [UsageLogUnavailable].
- Future<UsageReading> read() — Every record in the log.
- Stream<void> get changes — An event after each record this app appends.
- Future<void> appendUntilWritten(UsageRecord record, {Duration firstWait = const Duration(milliseconds: 250)})
class UnavailableUsageLog — No usage log: nothing is written, so no paid call starts.
- const UnavailableUsageLog()
class MemoryUsageLog — A usage log in memory, for the tests and the agent build, which must not write the user’s usage folder.
- MemoryUsageLog({this.device = '00000000-0000-4000-8000-000000000000'})
- final String device — The id [deviceId] answers.
- final List<String> lines — The lines written, oldest first, without their line feeds.
- int failing — How many of the next appends fail, as a write that cannot take the lock fails.
- List<UsageRecord> get records — The records written.

`lib/src/usage_log_stub.dart`

function UsageLog openUsageLog(String folder, { Duration lockTimeout = const Duration(seconds: 10), Duration retryEvery = const Duration(milliseconds: 50),… — No files on this platform: the web keeps no usage (Software Specification §6.7).

`lib/src/write_cancelled.dart`

class WriteCancelled — A write its caller stopped on purpose, raised from the bytes’ stream: the store logs it as a Stop, not a failure.

Internal

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

lib/src/directory_source_io.dart: canOpenDirectories, directoryProjectSource, directoryExists, osErrorCodeOf, ProjectPathException, DirectoryProjectSource, _Write, _Reading
lib/src/directory_source_stub.dart: canOpenDirectories, directoryProjectSource, directoryExists, osErrorCodeOf
lib/src/library_install_io.dart: installLibraryIfEmpty
lib/src/log_file_io.dart: FileLogSink, openFileLogSink
lib/src/project_bootstrap_io.dart: bootstrapProjectFolder, bootstrapProjectFolderFailingAt
lib/src/project_bootstrap_stub.dart: bootstrapProjectFolder, bootstrapProjectFolderFailingAt
lib/src/project_creator_io.dart: canCreateProjects, copyImportedProjectTo, ProjectFolderNotEmptyException, ProjectFolderIsLinkException, NotAProjectFolderException, createProject, copyProjectTo, deleteProjectFolder, isDeletableProjectFolder, sameFolderPath, _segments, _comparable
lib/src/project_folder_take_back_io.dart: takeBackProjectFolder
lib/src/usage_log_io.dart: FileUsageLog, openUsageLog