Software specification

Published reference snapshot

Version 1.2 · 10 September 2026. The application repository maintains this document. Download the exact Markdown snapshot.

This snapshot includes source changes that were uncommitted when imported.

The desktop application that reads, browses and (later) edits FilmOpen projects.

Version	1.2
Date	10 September 2026
Status	Describes the code at the end of milestone 3
Companion documents	FilmOpen Project Specification 1.5 (docs/FilmOpen-Project-Specification v1.0.md) defines the file format this software reads and writes. FilmOpen — Milestone 1, 2 and 3 (docs/FilmOpen-Milestone *.md) record what was built, why, and what comes next.
Repository	filmopen-c, branch round-03-c (milestone 3), on top of round-02-c (milestone 2) and c (milestone 1)

---

Contents

1. Purpose
2. Design principles
3. Technology
4. Architecture
5. The model layer
6. Services: where files come from
7. State: providers
8. The tree
9. The user interface
10. Localisation
11. The sample project
12. Testing
13. Conventions for contributors
14. Known limitations
15. Third-party code Appendix A — File map Appendix B — Glossary of code names

---

1. Purpose

A FilmOpen project is a folder of plain JSON files describing a film completely: characters, outfits, locations, props, styles, documents; the script as seasons, episodes, sequences and scenes with their blocks; shots and cues; models, platforms and plugins; render batches; commentary; and official pointers. Every entity file is versioned per author (ch_main-hero_30yo_john123_v2.json), forking copies a file into a new author’s name, and a small _official.json pointer names the version the project has chosen. The intent is that a film is developed the way software is developed: many people, many versions, comparison, and a deliberate choice of what is official.

FilmOpen the application is the reader and editor for such folders. Milestone 1 delivered the reader: open a folder, see the whole project as a tree, inspect any object, see every version of it side by side, see the media rendered for it and what people said about it, and be warned about everything the format’s rules say a reader should warn about. Milestone 2 made it a desktop application that lives on a machine: it knows where a project’s media is (the manifest, §4.4 of the format), where the shared library of models, platforms and plugins is, where its own preferences and log are, which projects the user has opened, and it can create a project folder. Milestone 3 made it a writer: a new project comes with its creator’s first project file, the project file is edited in a form that saves as you type, any version can be forked, a director sets official with a star, anyone picks their preferred version with a check, and a version can be labelled.

The application is not the format. The Project Specification is authoritative about what files mean; this document is authoritative about how the application is built. Where the application simplifies the format’s rules, this document says so.

1.1 Audience of this document

A developer, or an AI development session, who has read the Project Specification and needs to continue the code without re-deriving its structure. It explains what exists, the reasons behind the shape of it, and the rules that must stay true when adding to it.

---

2. Design principles

These follow directly from the format’s own principles (Project Specification §2) and from decisions made during milestone 1.

1. Warn, don’t enforce. No file is rejected for being imperfect. A header that disagrees with its filename, a field of the wrong type, a segment that is too long, an unknown file: each is a warning the user can see, never a crash and never a silent fix. The loader tolerates any JSON that parses to an object.
2. Never guess. When the format says a reader must report rather than choose, the application reports. An ambiguous reference (several authors, nothing official, no viewer) is unresolved, not first-match. A folder with several project authors and no official pointer asks which to open. An implicit epoch falls back to default only, never to “whatever exists”.
3. The files are the only state. Every write goes to a file through the project’s ProjectSource, and the project is re-read afterwards; nothing is edited in memory and saved later. The app writes only under the viewer’s own handle (§17, §18.3 of the format): a form is offered on the viewer’s own version and Fork on everyone else’s; the official pointer is a director’s to write and to remove; the pick lives in the viewer’s own commentary file. Reads and writes are confined to the project folder; the media root and the library are sandboxes of their own, and the library is never written. Creating a project refuses a folder that already holds files.
4. The model knows the format, not the screen. Everything under lib/models/ and lib/services/ is pure Dart, free of Flutter and free of user-facing text. Diagnostics are codes with arguments. This keeps the core testable without a widget tree and ready to become a separate package.
5. Language-independent by construction. Every string a person reads comes from a localisation file, including the display labels for the format’s own field names, entity types and counts. The format’s JSON keys are never translated; the screen is.
6. One navigation path. Whatever is clicked, in the tree or in the detail pane, goes through one controller that sets what is shown, highlights the matching tree row and reveals it.
7. Small, honest surface. The application says what it does not do (placeholders show a message, the README says “nothing writes yet”). Product text is not aspirational.
8. Model after API Dash. The window layout follows the API Dash desktop client: a narrow icon rail, a resizable sidebar, a main pane. One component is adapted from it under its licence; the rest is FilmOpen code.

---

3. Technology

Concern	Choice	Notes
Language and toolkit	Dart 3.13, Flutter 3.47 (stable)	Windows desktop is the first target; the same code runs in Chrome for previews and in widget tests.
State	flutter_riverpod 3	Notifier / AsyncNotifier / Provider only; no code generation.
Split view	multi_split_view 3.6	Wrapped in widgets/split_view.dart, adapted from API Dash.
Folder picker	file_selector	Desktop only; hidden on the web.
Preferences	shared_preferences (SharedPreferencesWithCache)	Theme, language, viewer handle, sidebar width, verbose logs, recent projects, library folder. See §6.4 for where the file lives.
Application folders	path_provider	The app-support folder (preferences, shared library) and, on mobile, the log folder. Desktop log folders are computed from the environment (§6.4).
File browser and URL schemes	url_launcher	Only for the mobile “show in folder” branch; desktop uses the OS command directly.
Localisation	flutter_localizations, intl 0.20, Flutter gen-l10n	ARB files in lib/l10n/; generated code committed.
Lints	flutter_lints 6	flutter analyze must report no issues.
Tests	flutter_test	Unit, fixture and widget tests; 40 at the end of milestone 1, 83 at milestone 2, 104 at milestone 3.

Platforms enabled: windows, web. Android, iOS, macOS and Linux are not configured; the code has branches for them (paths, file reveal) that compile but have not run.

3.1 Commands

flutter pub get            # also regenerates localisations (generate: true)
flutter gen-l10n           # regenerate localisations by hand after editing ARB files
flutter analyze
flutter test
flutter run -d windows
flutter run -d chrome
flutter run -d web-server --web-port 8642 --web-hostname localhost   # headless preview
flutter build windows --release   # build\windows\x64\runner\Release\filmopen.exe

The Windows toolchain needs Visual Studio Build Tools with the C++ desktop workload; flutter doctor must show Visual Studio – develop Windows apps as OK.

---

4. Architecture

4.1 Layers

lib/
  models/      the format: filename grammar, entities, the project index, resolution, diagnostics   (pure Dart)
  services/    where files come from and go to (disk, bundled assets, memory), the loader, the manifest's
               media root, the shared library, the log, application folders, the file-browser reveal,
               what a new project contains (project_template), the writer (save, fork, official, pick)
               (pure Dart except asset_source and the *_io / *_stub pairs, which are conditional imports)
  providers/   Riverpod state: the open project, browser navigation, settings, localisation
  tree/        the tree model and the builder that lays a project out as a tree
  screens/     pages: dashboard, browser (tree pane, detail pane and its tabs), settings
  widgets/     reusable pieces: tree view, split view, attribute view, screenplay view, chips
  l10n/        ARB files, generated localisations, label helpers, field-label table
  utils/       natural (numeric-aware) string ordering
  theme.dart, app.dart, main.dart, consts.dart

Dependency rule. Arrows point downward only:

screens → widgets → providers → tree → l10n
                                  ↓
                             models ← services (project_source only)

• models/ imports nothing from Flutter and nothing from the layers above. It imports services/project_source.dart (an abstract interface plus an in-memory implementation), which is also pure Dart. This is a known small inversion, accepted for now; a later package split would move ProjectSource into the model package.
• services/asset_source.dart is the one Flutter-dependent service (it reads the asset bundle) and is imported only by providers/. services/app_log.dart and project_creator’s model inputs are pure Dart. Every service that needs dart:io comes as a triple — x.dart (a conditional export), x_io.dart, x_stub.dart — so the same call compiles on the web and answers “not available” there: directory_source, asset_disk, app_paths, log_file, reveal, project_creator, library_install.
• tree/ depends on Flutter only for IconData; icons are chosen in widgets/entity_icons.dart.
• l10n/labels.dart is the single bridge from model codes to human text.

4.2 Data flow

project folder ──┐
media root  ─────┤  three ProjectSources (folder / assets / memory), each its own sandbox
shared library ──┘  listPaths(), readText(), locate(), diskPath(), related()
      ▼
ProjectWriter ◄── (save / fork / official / pick: writeText, deleteFile on the project's source, then a re-read)
      ▲
ProjectLoader ──► FilmProject (manifest, media root, library; index: entities by stem (with origin),
      │            groups by type+tag, epochs, versions, official pointers, commentary, batches,
      │            takes (with media location), other files, warnings, project candidates,
      │            selected project)
      ▼
projectProvider (AsyncNotifier)  ◄── libraryProvider (FutureProvider: the library folder, seeded on first run)
      │
      ├─► treeModelProvider ──► TreeBuilder(project, l10n, viewer) ──► TreeModel(roots, index by selection key)
      │                                                                     │
      ▼                                                                     ▼
browserProvider (BrowserState: selection, highlighted node, toggled rows) ◄── TreePane clicks / DetailPane links
      │
      ▼
DetailPane: switch on Selection → ProjectOverview | ProjectChooser | CategoryView | EntityDetail | BatchDetail | OtherFilesView

Everything is derived: change the project, the viewer handle or the language, and the tree and pane rebuild from the index. Nothing is cached beyond Riverpod’s own memoisation. A write is a file write followed by refresh(): the new index replaces the old, and because the browser resets its navigation only when the source changes (projectSourceKeyProvider), the page being edited stays where it is.

---

5. The model layer

5.1 Filename grammar — models/stems.dart

FileNameParser.parse(path) implements Project Specification §5.4 and returns one of a sealed set:

Class	Filename shape	Holds
VersionStem	<type>_<tag>[_<epoch>]_<author>_v<n>	type, tag, epoch?, Author, v; stem, versionsKey (ch_main-hero_30yo), groupKey (ch_main-hero)
OfficialStem	<type>_<tag>[_<epoch>]_official	type, tag, epoch?; versionsKey
CommentaryStem	cm_<type>_<tag>_<author>	target type, tag, author
BatchStem	rd_<id>_<author>	id, author
TakeName	<deliverable>_<source stem>_r<id>_<renderer>_<n>.<ext>	deliverable, source VersionStem, batch id, renderer, n, extension; batchStem
UnknownName	anything else	the path

Rules enforced by the parser: exact token counts per type (library types carry an epoch, spec types do not); v<n> with n ≥ 1; take number n is a positive integer without leading zeros; the reserved owner official is never accepted as an author; a take’s batch token is r followed by at least one character. parseStem(stem) parses a stem without extension, as found in forkedFrom and batch source fields.

namingWarnings(parsed) returns warnings (as codes) for any segment outside [a-z0-9][a-z0-9-]{0,19} or longer than ten characters (§5.2). It is applied to every parsed name, including takes and commentary.

Author (models/author.dart) splits owner[.workspace]; equality is by full handle.

EntityType (models/entity_type.dart) is the enum of the nineteen prefixes with category (library / spec / commentary / renderBatch), hasEpoch, isVersioned, and the dotted-tag containment rules parentType / containedType (outfits nest under characters; areas under locations). Deliverable is the enum of take prefixes with isImage. Neither enum carries display text.

5.2 Documents — models/entity.dart

• Entity: one versioned file. Holds the VersionStem, the project-relative path and the complete json map (unknown fields preserved). Typed accessors (name, label — the version label of §7, forkedFrom, notes, kind, stringList(key), blocks) never throw on a wrong JSON type. headerMismatches and fieldTypeWarnings return warning codes.
• OfficialPointer: from an _official.json; fromJson returns null when the official field is missing, which the loader reports. Keeps its whole json so the writer can rewrite it without losing fields.
• Commentary / CommentaryEntry: one cm_ file with prefer — the author’s pick — and entries (on, at, rating ±1, text, block, field); keeps its whole json for the same reason.
• RenderBatch / RenderItem: one rd_ file with its items; totals cost.
• Take: a media file discovered by name; never listed inside an entity (§12.1).

Two helpers, stringField(json, key) and numField(json, key), are the only way JSON scalars are read.

5.3 The index — models/project.dart

FilmProject is immutable after loading and holds:

Field	Content
entitiesByStem	every versioned entity by full stem
groupsByKey	EntityGroup per type+tag; each group holds EntityVersions per epoch (spec types use the single epoch null); versions are sorted by author handle then number
officialsByKey	pointers by versions key
commentaries, batches, takes	as discovered
companionFiles	named by the grammar but not JSON (a plugin’s .js beside its manifest)
otherFiles	not named by the grammar; reported, never touched
warnings	every ProjectWarning raised while loading
projectCandidates	every pj version in the folder, stable order
selectedProject	the pj version in use, or null when the user must choose (needsProjectChoice)

Queries: group(type, tag), groupsOf(type) in natural tag order, childGroups(type, parentTag) for dotted tags one level down, officialPointer / officialEntity / isOfficial, takesFor(group), commentaryFor(group), batch(stem), groupCounts. withSelectedProject(entity) answers the chooser without reloading.

5.3a Project-level knowledge — models/project_kind.dart, models/epochs.dart

ProjectKind is the enum of §8.1 (short, feature, miniseries, series) with the 1.4 words read as their nearest value (fromName), isEpisodic (seasons and episodes rather than installments and acts, §10.1) and defaultRootKey (the story-root list a blank project of that kind starts with, §8.5). recommendedGenres is the vocabulary of Appendix A.9. EpochDeclaration / declaredEpochs(json) read the project’s epochs object in the order §8.2 defines (unnumbered first in file order, then by order); encodeEpochs(list, previous:) writes it back renumbered 1..n, keeping fields the app does not know. FilmProject exposes kind, declaredEpochList, defaultEpoch (the first declared, else default), epochLabel, sortedEpochs(...) (declared order, then natural), isDirector(author) (§8.3), commentaryBy, pickOf(group, viewer) and isPickOf.

5.4 Resolution — FilmProject.resolve

Implements §6.1 in a simplified but faithful form. Given a type, a reference (tag or full stem), an optional epoch, whether that epoch was explicit, and an optional viewer:

1. A full stem names its file exactly.
2. No such tag → unresolved (noEntity).
3. Epoch: for library types the wanted epoch is the given one or the project’s default epoch (the first it declares, §8.2; default when it declares none). If there is no file for it: an explicit epoch, or the default itself, is unresolved (noEpoch); an implicit epoch falls back to the default and marks fellBack; no file at the default either → unresolved (noEpochOrDefault).
4. Author: the viewer’s own highest version, then the viewer’s owner’s highest; then the official version; then, if exactly one owner has versions, that owner’s highest.
5. Otherwise unresolved (ambiguous, listing the owners).

Not implemented from §6.1: the rule that a file named by an official pointer resolves through official only (the “official sees the official world” half). The application resolves from the viewer’s point of view for every file. This is recorded as a milestone 2 item.

5.5 Project selection — ProjectLoader._selectProject

Implements §4.1: a valid official pj pointer wins; else a sole author’s highest version; else no selection and the UI asks. Several project tags in one folder also ask. An official pointer to a missing file is a warning and falls through as if absent.

5.6 Diagnostics — models/diagnostics.dart

ProjectWarning(kind, args, path) with WarningKind (twenty-five kinds: naming, duplicate stem, header missing or mismatched, field type, official pointer problems, unreadable JSON, project selection, since milestone 2 the manifest and library kinds: noManifest, manifestTagMismatch, dataLocatorMalformed, dataLocatorUnsupported, dataRootUnavailable, dataRootAbsolute, libraryStemShadowed, libraryUnavailable, and since milestone 3 noEpochsDeclared, §8.2). ResolutionProblem(kind, type, reference, epoch, owners) with ProblemKind (five kinds). Both have a toString() for logs only; the UI renders them through the localisation layer.

5.7 The manifest — models/manifest.dart

filmopen-project.json (Project Specification §4.4) is the one file in a project that is not somebody’s versioned work. ProjectManifest.fromJson reads tag, data and note tolerantly (a missing or mistyped field is null and the loader warns). DataLocator is the typed “where”: LocatorType (local, dropbox, google-drive, onedrive, icloud, url) or an unknown name kept as text; isLocal, isAbsolutePath (POSIX, drive-letter and UNC forms). ProjectManifest.template is what the creator writes. projectManifestFileName is the one constant that names the file.

5.8 Short names — models/short_name.dart

The format’s segment (§5.2) as a person types it: ShortName.pattern ([a-z0-9][a-z0-9-]{0,19}), validate (a ShortNameProblem: empty, invalid characters, bad start, too long), isLongerThanRecommended (over ten: warn, never refuse), normalise (free text to the nearest segment, never inventing one). The filename grammar in stems.dart uses the same pattern, so there is exactly one place the rule lives; widgets/short_name_field.dart is the input box built on it.

5.9 Origin — Entity.origin, Take.media

EntityOrigin { project, library } says which root a versioned file came from; EntityGroup.isFromLibrary is true when every version of an entity came from the library. Take.media is the MediaLocation resolved at load time, because a take may sit in the media root rather than the project folder.

---

6. Services: where files come from

ProjectSource (services/project_source.dart) is the abstraction the loader reads through. One source is one root; a project’s media root (§4.4) and the shared library (§14.5) are sources of their own:

String get label;                       // folder name, or a neutral label
String? get rootPath;                   // absolute path when it is a folder
Future<List<String>> listPaths();       // root-relative, '/'-separated, recursive
Future<String> readText(String path);
MediaLocation? locate(String path);     // AssetMedia(key) | FileMedia(path) | null
String? diskPath(String path);          // absolute path on this machine, for the file browser; null if not on disk
Future<ProjectSource?> related(String relativeFolder);  // the folder a manifest names: '../x-data', 'media'; null if absent
bool get canWrite;                      // false for bundled assets
Future<void> writeText(String relativePath, String text);   // create or replace, through the same sandbox check
Future<void> deleteFile(String relativePath);               // absent is not an error

MediaLocation keeps the model Flutter-free; widgets/media_image.dart turns it into an ImageProvider.

Implementations:

• DirectoryProjectSource (directory_source_io.dart, desktop): recursive scan that skips hidden entries and the folders build, conform, node_modules. Every read goes through file(relativePath), which rejects schemes, absolute paths, backslashes, empty, . and .. segments, then checks that the absolute path, and the symlink-resolved path when the file exists, lies inside the folder. Violations throw ProjectPathException. related() resolves .. against the folder’s URI (or takes an absolute path as given) and returns a new DirectoryProjectSource — a sandbox of its own, never a hole in this one — or null when the folder does not exist. A conditional export (directory_source.dart) swaps in a stub on the web, where canOpenDirectories is false.
• AssetProjectSource (asset_source.dart): a folder bundled as assets — the sample project, its media root the-cartographer-data, the seed copy of the library — enumerated from the asset manifest. related() resolves a sibling asset folder; diskPath() finds the file beside the executable (asset_disk_io.dart: <exe dir>/data/flutter_assets/… on Windows and Linux, the App.framework bundle on macOS) so that even the sample’s files can be shown in the file browser. It is read-only (canWrite false); snapshot(label:) copies its text files into a writable MemoryProjectSource whose media root is still the bundled folder — how the web preview opens the sample, so editing can be tried where there is no disk.
• MemoryProjectSource: a Map<String, String> for tests and fixtures, and for session-only projects (the web), with a relatedSources map for the folders a manifest may name. Writable.

ProjectLoader.load(source, {library}) (services/project_loader.dart) works from up to three roots. It reads the manifest first (a missing one is noManifest; a manifest without filmopen or tag is headerMissing; the folder without a manifest is its own media root) and opens the media root it names when the locator is local and the folder exists (else dataLocatorUnsupported / dataRootUnavailable; an absolute path is dataRootAbsolute). It indexes the library’s files first with EntityOrigin.library (a library folder that cannot be listed is libraryUnavailable and the project goes on without it), then the project’s with EntityOrigin.project — the project’s copy of a stem replaces the library’s with libraryStemShadowed and none of the replaced file’s own warnings survive (per-entity warnings are emitted at the end); a project’s official pointer replaces a library’s silently (§14.5: accepting a library entry is pointing official at it); the library’s unknown files are not the project’s “other files”. Then it walks the media root for takes only (anything else there is reference material reached by path, §6.3). Finally it builds the index as in milestone 1, checks the manifest’s tag against the pj files (manifestTagMismatch) and selects the project. It logs one project.loaded debug entry with counts and timing.

6.1 Creating a project — services/project_template.dart, project_creator*.dart

writeNewProject(source, {tag, author, name, kind, epochLabel}) (pure Dart) writes into any writable ProjectSource: filmopen-project.json from ProjectManifest.template, and pj_<tag>_<author>_v1.json with the header, the kind, an empty genre, the current year, one epoch (default, labelled in the user’s language, with the current year, §8.2), the creator in contributors as director (§8.3), an empty story-root list for the kind (§8.5) and timestamps. createProject(...) (_io) makes <parent>/<tag>/ first, refusing a folder that already holds files (ProjectFolderNotEmptyException) and a tag that is not a segment; where folders cannot be made (the web) the provider writes the same documents into a MemoryProjectSource that lives for the session. encodeProjectJson is the one JSON encoder for written files: two-space indentation and a final newline (§18.1); rfc3339Now() the one timestamp format (§7).

6.1a Writing — services/project_writer.dart

ProjectWriter(project) is pure Dart and does every write into an open project, through project.source.writeText / deleteFile, logging each (entity.saved, entity.forked, official.set, official.cleared, pick.set):

• saveEntity(entity, json, viewer:) — replaces the author’s own file with json plus a fresh updated. Refuses a read-only source (ProjectReadOnlyException), a library file, no viewer (NoViewerException) and another author’s file (NotYourFileException, §17 rule 2). Whether to warn that the version is official (§13.2) is the caller’s decision; the editor shows a banner and still allows it.
• fork(entity, viewer:) — §13.1: the viewer’s next number at that epoch (v1 when they have none), a complete copy with author, v, forkedFrom and fresh timestamps, minus the version label; written beside the original. Returns the new VersionStem.
• setOfficial(entity, viewer:) / clearOfficial(entity, viewer:) — writes <versions key>_official.json naming the entity with setBy and setAt (rewriting an existing pointer’s other fields, dropping its note), or deletes the pointer file. The UI offers this to directors only (FilmProject.isDirector, §8.3).
• setPick(group, entity?, viewer:) — prefer in the viewer’s own cm_ file for the entity (§13.4), created with empty entries when they have none; null removes prefer and keeps the file.

Nothing renames or deletes another author’s file (§18.3).

6.2 The log — services/app_log.dart, log_file*.dart

Structured logging, pure Dart. LogLevel is verbosity from error to trace; error and warning are always written, info is the default threshold, debug is what the Verbose logs setting adds, trace is per-file detail that only FILMOPEN_LOG_LEVEL=trace in the environment turns on (the environment pins the level; the setting then cannot lower it). AppLog.instance fans each LogEntry (UTC ts, level, dotted event such as project.opened, a data object, optional error and stack) to its sinks: FileLogSink (one JSON object per line, appended and flushed synchronously so a crash loses nothing, rotated to <name>.1.jsonl past 5 MB), LineLogSink (the console in debug builds), MemoryLogSink (tests). A sink that throws is skipped, never fatal. AppLog.timed wraps a future and logs its duration or its failure. main.dart opens the file sink before anything else, routes FlutterError.onError and PlatformDispatcher.onError into it, and writes app.started. Events are identifiers, not sentences, so the log stays language-independent and groupable.

6.3 Showing files — services/reveal*.dart

revealInFileManager(path) opens the platform’s file browser with the file selected (or the folder opened): Windows explorer.exe /select, <path> (the switch and the path as two arguments — Dart quotes an argument containing spaces, and Explorer ignores a quoted /select,C:\a b\f), macOS open -R, Linux the freedesktop org.freedesktop.FileManager1.ShowItems D-Bus call with xdg-open of the folder as fallback. iOS (shareddocuments://) and Android (a content:// Documents URI for shared storage) go through url_launcher and are best-effort: those platforms are not built here and the branches have not run. It returns false rather than throwing, and the caller says so in a snackbar. On the web canRevealFiles is false and the buttons are not shown.

6.4 Application files — services/app_paths*.dart

Where the application keeps its own files, in the place each operating system expects. Project data never lives here.

	Preferences (shared_preferences)	Shared library	Log file
Windows	%APPDATA%\ai.filmopen\filmopen\shared_preferences.json	%APPDATA%\ai.filmopen\filmopen\library\	%LOCALAPPDATA%\FilmOpen\logs\filmopen.jsonl
macOS	NSUserDefaults (~/Library/Preferences/<bundle id>.plist)	~/Library/Application Support/<bundle id>/library/	~/Library/Logs/FilmOpen/filmopen.jsonl
Linux	$XDG_DATA_HOME/filmopen/shared_preferences.json (~/.local/share/…)	$XDG_DATA_HOME/filmopen/library/	$XDG_STATE_HOME/filmopen/logs/ (~/.local/state/…)
Android	the system SharedPreferences store	the app’s support folder, library/	the app’s support folder, logs/
iOS	NSUserDefaults	the app’s support folder, library/	the app’s support folder, logs/
Web	browser storage	the bundled copy, read in place	none: console only

The app-support folder is the one path_provider derives from the executable’s company and product names (windows/runner/Runner.rc: ai.filmopen, filmopen). On Windows and Linux shared_preferences keeps a JSON file there, and Settings → About shows that file with a show-in-folder button; on macOS and mobile the plugin uses the system’s own preference store, which is not a file to show, so the line is absent. The library sits in the same folder so everything the app owns on a machine is in one place; a library folder that cannot be read is a libraryUnavailable warning on the project, shown on the Settings library card, never a failure to open. Preferences are plain JSON: theme, language, handle, widths, verbose flag, recent project paths, library path — nothing secret. API keys and other credentials, when they arrive, go to the platform’s credential store (Windows Credential Manager / DPAPI, the macOS and iOS Keychain, the Android Keystore, libsecret on Linux), not to this file; the code says so at sharedPreferencesProvider.

Note for development: two builds of the app on one machine (for instance filmopen-a and filmopen-c) share these folders and the log file, because they share the product identity.

6.5 Installing the library — services/library_install*.dart

installLibraryIfEmpty(folder, seed) copies the bundled library (assets/sample/library) into the app’s library folder when that folder holds no files (empty subfolders do not count) and never touches it afterwards. Updating the library — a git pull, a download — is the user’s or a future updater’s job, independent of the app’s own builds (§14.5). On the web the bundled copy is read in place.

---

7. State: providers

Provider	Type	Responsibility
projectProvider	AsyncNotifier<FilmProject>	Loads the sample at start — read in place on desktop, as a writable session copy on the web — with the library from libraryProvider (which it watches: choosing another library folder re-reads the open project). openDirectory(path), openSample() replace the page (loading spinner) and, on success, put the folder at the top of the recent list. createProject(...) writes the folder (or a session-only project where there is no disk) and opens it, returning the new pj stem. refresh() re-reads without entering a loading state, so the current project stays on screen. selectProject(stem) answers the chooser. saveEntity, fork, setOfficial, setPick call the ProjectWriter with the viewer from Settings and then refresh(). Every open, write, success and failure is logged.
projectSourceKeyProvider	Provider<String?>	Names which source is open (type and root path or label), unchanged by a re-read. The browser resets its navigation on this, not on every new index, so a page survives the re-read that follows a save.
settingsProvider	Notifier<Settings>	themeMode, viewerHandle (empty = no viewer), sidebarWidth, locale (null = platform), verboseLogs (applied to AppLog.instance on load and on change), recentProjects (most recent first, at most twelve, each a {path, name} JSON string; unreadable entries are dropped), libraryPath (null = the app’s own folder). Persisted through sharedPreferencesProvider, which main overrides with a real store and tests leave null.
libraryProvider	FutureProvider<ProjectSource?>	The shared library: the folder chosen in Settings; else the app’s library folder, seeded from the bundled copy on first run; else (web) the bundled copy read in place.
preferencesLocationProvider	FutureProvider<String?>	The preferences folder, for Settings → About; null on the web.
localizationsProvider	Provider<AppLocalizations>	The strings in effect for code without a BuildContext: the chosen locale, else the platform locale, resolved to a supported one by language code. Widgets use context.l10n; both resolve the same way.
treeModelProvider	Provider<TreeModel>	Rebuilds the tree from the project, the viewer and the language.
browserProvider	Notifier<BrowserState>	selection (what the detail pane shows), nodeId (highlighted row), toggled (rows flipped from their default expansion). navigate(selection, {nodeId}) is the only way to change what is shown; without a node id it looks the row up via TreeModel.nodeIdFor and expands its ancestors. toggle(node), setAllExpanded(bool). Resets to the overview when another source is opened (projectSourceKeyProvider), not on a re-read.
treeFilterProvider	Notifier<String>	The sidebar filter text.
navIndexProvider	Notifier<int>	Which rail page is shown.

Expansion state stores toggles away from the default rather than the expanded set, so a freshly loaded tree keeps sensible defaults (Script expanded, Characters expanded, scenes collapsed) without a reset step.

---

8. The tree

8.1 Model — tree/tree_node.dart, tree/selection.dart

TreeNode: id (stable, path-like), label, detail (muted secondary text), tooltip, icon, selection (what clicking shows; null for pure groupings), children, initiallyExpanded, isOfficial (star), isPick (the viewer’s pick, a green check), hasProblem (warning icon, error-coloured).

Selection is sealed: ProjectOverviewSelection, CategorySelection(type), EntitySelection(type, tag, {epoch, stem}), BatchSelection(stem), OtherFilesSelection. Each exposes matchKeys, most specific first (entity:<stem>, entity:<type>:<tag>@<epoch>, entity:<type>:<tag>), which TreeModel indexes so a link from the detail pane can find and highlight the right row even when it names a version the tree does not show.

8.2 Builder — tree/tree_builder.dart

Top-level rows, in order:

1. Project — name, tag, its pj versions as children with the official star; flagged when a choice is pending.
2. Script — the selected project’s story roots (seasons / episodes / sequences / scenes, whichever the file has), each unit’s own child list beneath it, in the file’s order. A scene gets Shots and Cues wrapper rows; any unit but a season gets Cues. A wrapper lists the unit’s explicit shots / cues order or, absent that, every <unit>.<n> group in natural order (the tooltip says which). Empty wrappers are omitted; units and warning rows never are. Unresolved references are warning rows with the reason; a unit that lists one of its own ancestors is a circular story reference row and is not recursed into. A unit resolved by falling back to default says so in its tooltip.
3. Characters, Locations, Props, Styles, Misc, Documents — each entity by tag, then its epochs in the project’s declared order (§8.2), then one version row per author showing that author’s latest version (author vN, with the version label or from <stem> as detail; official star; the viewer’s pick as a check). The tree does not list every iteration: beneath an author’s row sit only the older versions of theirs that still matter — the official one and the viewer’s pick. Dotted tags nest under their parent (outfits under a character as Outfits, areas under a location as Areas); one whose parent file is missing is listed at the top level with a warning. The same version rule applies to the project’s own versions and to models, platforms and plugins.
4. Models, Platforms, Plugins — entity, then versions.
5. Render batches — r<id> with author, kind and item count.
6. Other files — present when the folder holds companion or unknown files.

Every visible string comes from the AppLocalizations the builder is given.

8.3 Widget — widgets/tree_view.dart

A flat, virtualised ListView over the visible rows. A row shows indent, chevron (toggles), icon, label plus muted detail as one rich text, then the star or warning icon. Tap selects when the row has a selection, otherwise toggles. There is deliberately no double-tap handler: it would delay every single tap by the double-tap timeout. With a filter, only rows that match or have a matching descendant are shown, fully expanded.

---

9. The user interface

9.1 Window

Dashboard: a 64-pixel rail (Project, Settings, About) beside an IndexedStack of pages. The browser page is a SidebarSplitView (sidebar 220–560 px, seeded from settings, saved on drag end) with TreePane left and DetailPane right. Material 3, ColorScheme.fromSeed, compact density, light and dark themes, and an AppColors theme extension for the two semantic colours the scheme lacks (the official star, a positive rating).

9.2 Tree pane

Header with project name and subtitle (folder path, or “bundled sample”), a chip showing the viewer handle when one is set, expand-all / collapse-all, and the project menu (⋮): New project… and Open project… (desktop only), Re-read files, then a Projects section listing the bundled sample and every folder opened before (name, path), the open one ticked. Choosing a remembered folder that no longer exists removes it from the list with a snackbar, and the project on screen stays. Below the header, the filter field and the tree.

New project dialog (screens/browser/new_project_dialog.dart): parent folder (desktop only; typed or browsed; pre-filled with the folder of the last opened project), the short name in a ShortNameField, an optional title, the username (a ShortNameField accepting owner[.workspace], pre-filled from Settings, mandatory: “Lowercase letters, digits and dashes. All your files will contain this username”), and the kind (a pull-down of §8.1). It says which project file it will write and that the creator is its director, refuses a non-empty folder with a message, saves the username to Settings when it differs from the handle there, creates and opens the project, and the caller takes the user to the new project file’s page, whose Edit tab is first. On the web the dialog says the project lives in the browser session only.

ShortNameField (widgets/short_name_field.dart) is the one input box for anything that must be a segment (§5.2): it filters as the user types (lower case, spaces and underscores to dashes, other characters dropped, twenty at most), explains the remaining problem under the box, and warns above ten characters without refusing. With allowWorkspace it accepts one dot and validates both sides, for an author handle (§5.6). Any place that asks for a tag, an epoch token or a handle reuses it.

9.3 Detail pane

Switches on the selection. When the project needs a choice, the Project chooser replaces everything: a card per pj candidate (name, stem, author, version, language, forked-from) that selects it.

• Project overview — name, logline, stem chip (click opens the pj entity), official chip, source chip, a filmopen-project.json chip (or a No manifest chip) and a Media: … chip naming the media root (or Media in the project folder); synopsis; cards for Details (kind and genres in words), Contributors, Epochs (one chip per epoch in order — token, label, year — the first marked as default), Tracks; Contents of the folder as count chips that open the category (entities the library contributed are not counted here); a Shared library card with where it was indexed from and its own counts; Warnings rendered in the current language.
• Category view — a list of every entity of one type with tag, epoch and version counts and an “official set” chip.
• Entity detail — header (name; chips for the type — named for the project’s kind for story levels, §10.1 —, stem, Shared library when the file came from the library, forked-from as a link, updated, kind); an Epoch row when the entity has several, in the project’s order; and the Version row: an Author pull-down (the authors with a version at this epoch; choosing one shows their official version if they have it, else their latest), a Version pull-down of that author’s versions (v2, or v2 · goth when labelled; star or check as trailing icon), the official star (a toggle: grey, yellow when set; enabled for directors of a writable project; setting writes the pointer, clearing deletes it), the pick check (a toggle: grey, green when set; enabled for any viewer of a writable project), a label button (the author only; a small dialog writes label), and Fork. Tooltips say why a control is disabled (no username, read-only, directors only). Then tabs:
  • Edit (project files only, first when present) — the project form (tabs/project_edit_tab.dart): title, kind (pull-down; changing it moves an empty story-root list to the new kind’s key), year, rating, genre (widgets/genre_picker.dart: a pull-down of check boxes over the recommended list plus whatever the file names, shown as chips), logline, synopsis, and the epochs (tabs/epochs_editor.dart: a reorderable list with a drag handle, token chip with a default badge on the first, label and year boxes, a remove button disabled for an epoch that files use or the last one, and Add epoch with a small dialog — token, label, year). Every change re-encodes the draft and saves it 700 ms after the last keystroke, with a status at the top right (Saved, Unsaved changes, Saving…, the error); a pending change is written when the page is left. An official version shows a banner offering Fork. On somebody else’s file, or a read-only project, the tab says so and offers Fork.
  • Overview — every attribute of the chosen file except the header, as a nested key/value view; labels are translated with the raw key on hover; lists of scalars become chips, lists of objects become boxed sub-views. A separate File card shows path and header dates; a red card lists header/filename disagreements.
  • Script (scenes only) — the blocks as a screenplay page: block ids in the gutter, action, centred character cue with (O.S.) / (V.O.) / ^, parenthetical direction, transitions right-aligned, titles, notes boxed.
  • Compare — the versions at this epoch as columns, ordered as §13.3: the version being viewed, the viewer’s own, the viewer’s pick, official, then the rest in author/version order. Rows are dotted leaf paths (appearance.hair.color) so each attribute diffs on its own; scene blocks align by id; differing rows are tinted. Copy-left (§13.3) is not implemented.
  • Takes — every take discovered for any version of the entity, as cards (image preview for image deliverables, placeholder icon otherwise), with deliverable, take number, source version, batch chip (opens the batch), renderer, path; “picked” marks takes the chosen version’s picks name.
  • Commentary — all authors’ commentary consolidated: a Preferences card, then entries newest first with rating icon, author, date, on chip, block/field chips, text.
  • JSON — the file pretty-printed with two-space indentation; top right, a folder button that shows the file in the platform’s file browser (disabled with an explanation when the file is not on disk; absent on the web) and a copy button.
• Batch detail — header chips (stem, author, kind, tier, status, created, item count, total cost) and a table of items; the source column links to the entity.
• Other files — two lists: named by the grammar but not JSON; not named by the grammar.

9.4 Settings

Appearance (System / Light / Dark), Language (System / English / Español; language names in their own language), Identity (the author handle, with helper text saying whether a handle is in effect), Shared library (what it is; the folder in use with a show-in-file-browser button; Choose folder…; Use default when a folder was chosen), Logs (what is logged; the Verbose logs checkbox; the log file’s path and a View log button that shows it in the file browser; on the web, a line saying entries go to the console), About (version, specification version, URL, the preferences folder with a show button, Open-source notices → Flutter’s licence page, which includes the vendored API Dash licence).

9.5 Behavioural rules

• The viewer handle is empty by default, so a first-run user sees the format’s rule that official wins. Setting a handle is visible in the tree header.
• Refresh never blanks the screen.
• Every empty state says what would fill it (no takes yet, only one version, no blocks).
• Every write goes through ProjectWriter and is followed by a re-read; the UI never edits the index. Writes happen only under the viewer’s handle; the star is for directors; the library is never written.
• On the web nothing reaches a disk: the sample and new projects are session copies, and the tree header says so.
• Every transient message goes through widgets/messages.dart (showMessage), so they all look alike and can carry one action (for instance Settings when a username is missing).

---

10. Localisation

Three layers, all in lib/l10n/:

1. Messages — app_en.arb (template) and app_es.arb, compiled by gen-l10n (l10n.yaml: nullable-getter: false) into app_localizations.dart and one file per language. Widgets use context.l10n; providers use localizationsProvider. Counts use ICU plurals (countScene(n) → “1 scene” / “3 scenes”).
2. The format’s vocabulary — the JSON keys are normative and never translated. fieldLabel(l10n, key) in field_labels.dart maps 310 keys from Appendix A to messages (fieldName, fieldForkedFrom, …) and returns null for unknown keys, in which case the raw key is shown. Entity types (typeScene, typeScenePlural, countScene) and deliverables (deliverableClip) have their own messages, reached through the Labels extension in labels.dart (typeLabel, typePlural, typeCount, deliverableLabel).
3. Diagnostics — warningText(ProjectWarning) and problemText(ResolutionProblem) in labels.dart turn model codes into sentences.

The generated files are committed so editors and the analyzer see them; every build regenerates them. To add a language: copy app_en.arb, translate, add the language name to settings_page.dart. To add a field label: add field<Key> to every ARB and one case to field_labels.dart. British spelling is used in English messages (colour, licence).

---

11. The sample project

assets/sample/ holds The Cartographer from Appendix B of the Project Specification, extended so the tree has depth, laid out the way a real project is meant to be (§4.4, §14.5):

• the-cartographer/ — the project: filmopen-project.json (tag cartographer, data → ../the-cartographer-data) and 40 JSON files, flat (folders carry no meaning in the format): two project versions (John’s, and Suda’s Thai remake forked from it) with an official pointer; the character main-hero at two epochs with three versions at 30yo and an official pointer to Maria’s fork; a second character; two outfits; two locations, one with an area; a prop, a style with an official pointer, a misc entry, a document; a season with two episodes, one using a sequence; two scenes, one of which has two versions and an official pointer; shots and cues including a J-cut and an episode-level music cue; two commentary files; two render batches; and one unknown text file so the Other files row appears.
• the-cartographer-data/ — the media root: the nine placeholder takes (four small PNGs, empty .mp4 and .wav files named as takes).
• library/ — the seed of the shared library: a model, a platform and a plugin manifest.

Being under assets/ and in Git is a development convenience (the build copies them to build/flutter_assets/assets/sample/…); a real project’s media root is a synced folder, and the real library is the folder the app installs beside its preferences.

The sample is what the app opens at start and what most tests read. In-memory fixtures (test/fixtures.dart) cover what the sample cannot: ambiguity, missing epochs, multi-author project folders, bad field types, cycles.

---

12. Testing

File	Covers
test/stems_test.dart	the filename grammar: every name kind, takes back to their source and batch, rejections, naming warnings, the reserved owner
test/project_test.dart	loading the sample: counts, warnings, resolution rules, the tree’s shape
test/fixture_test.dart	spec behaviours on tiny in-memory projects: ambiguous resolve, default-only fallback, project selection (ask, invalid pointer, sole author), tolerance of wrong types, leaf scenes and unresolved rows in the tree, cycle detection
test/directory_source_test.dart	the path sandbox on a real temp folder, and skipped folders
test/localization_test.dart	Spanish messages, field labels, diagnostics and tree text
test/widget_test.dart	the app: overview and tree, every entity tab lays out without overflow, tree highlight when choosing a version, navigation from the detail pane reveals the row, the project chooser
test/manifest_test.dart	the manifest and media root (§4.4): locators, takes found in the media root and beside the JSON, no manifest, unsupported type, missing folder, absolute path, malformed data, tag mismatch, a manifest missing filmopen or tag
test/library_test.dart	the shared library (§14.5): entries marked by origin, separate counts, project stem shadows the library’s with a warning and none of the replaced file’s warnings survive, a fork beside library versions, a project official pointer overriding silently, an unreadable library folder as a warning rather than a failure
test/short_name_test.dart	the segment rule in one place: validation, the ten-character advice, normalisation, and that the filename grammar warns by the same rule
test/app_log_test.dart	JSON-line shape, thresholds, verbose and the environment pin, a failing sink, unencodable data, timed, the file sink and its rotation
test/settings_test.dart	recent projects (tolerant parsing, order, no duplicates, cap), library path and verbose defaults
test/project_creator_test.dart	creating a project on a real temp folder: manifest and first version (director, one epoch, root list for the kind), the kind’s root list, refusing a non-empty folder and a bad tag
test/project_writer_test.dart	the writer on an in-memory project (§13, §17): save keeps unknown fields and stamps updated, refuses other authors, no viewer and read-only sources; fork numbering for own and others’ versions, labels not copied; official set (rewriting the pointer, dropping its note), new pointer, clear; pick set, file created, cleared; epoch order, re-encoding, default-epoch fallback, the no-epochs warning; kind vocabulary
test/editing_test.dart	editing through the screen on an in-memory project: the project form saves after the delay and the page survives the re-read, somebody else’s file offers Fork, Fork makes and shows the next version, the tree shows one row per author with official and pick beneath and the label as detail, the star and the check write their files and the star is disabled for a non-director
test/project_menu_test.dart	the ⋮ menu’s items, the New project dialog’s filtering, the mandatory username and the file it announces, the JSON tab’s folder button, the library chip

Widget tests load projects in setUpAll because file IO does not complete inside a widget test’s fake-async zone. Tree rows draw label and detail as one rich text; match them with find.text('label detail', findRichText: true).

flutter analyze and flutter test must both be clean before a commit. Tests that need dart:io import the _io file directly (log_file_io.dart), because the analyzer resolves a conditional export to its stub.

---

13. Conventions for contributors

• No user-facing text outside lib/l10n/. Models and services emit codes. Widgets take strings from context.l10n; providers from localizationsProvider.
• Every write goes through ProjectWriter (or writeNewProject for a new project), through the source’s writeText / deleteFile, followed by refresh(). No widget writes a file, and nothing edits the index in memory.
• Write only as the viewer. A write without a handle throws NoViewerException, another author’s file NotYourFileException; the UI turns these into messages and offers Fork or Settings.
• No Flutter imports in lib/models/, lib/services/project_source.dart or lib/services/app_log.dart.
• Platform code comes in threes: x.dart (conditional export), x_io.dart, x_stub.dart; the stub answers “not available” (canX = false, null, or UnsupportedError) and the UI hides the affordance. Never import dart:io from a file the web build reaches.
• Log events, not sentences: AppLog.instance.info('project.opened', data: {...}); dotted identifiers, structured data, no user-facing text. Log every open, write, failure and setting change; log timings at debug.
• One rule for short names: anything that must be a segment goes through ShortName and, in the UI, ShortNameField.
• Never throw on a bad file. Add a WarningKind and report.
• Never choose for the user where the Project Specification says report. Return an unresolved Resolution or a null selection.
• One way to navigate: browserProvider.navigate(...).
• Comments explain why, and cite the Project Specification section (§6.1) when a rule comes from it.
• Filenames and identifiers follow the format’s vocabulary: stem, tag, epoch, author, official, take, batch, cue, block.
• Tests for every spec rule on an in-memory fixture, not only on the sample.
• Keep kAppVersion in lib/consts.dart equal to version: in pubspec.yaml.
• Commit pubspec.lock (it is an application) and the generated localisation files.

---

14. Known limitations

• Only the project file has a form. Other entity types are read here; they are forked, starred, picked and labelled, but their content is edited by hand or by a later milestone (a JSON editor, then per-type forms).
• Character ages from epochs (§9.1 birthYear) are specified but not yet proposed by the app: the character form does not exist yet.
• No copy-left in Compare, and no per-attribute compare of two epochs of one entity (§13.3) yet.
• A save re-reads the whole folder. Fine for hundreds of files; a project of thousands would want an incremental index.
• Concurrent edits are not detected. The last write wins; an outside change is picked up by the next re-read (or Re-read files) when the form is clean.
• Locators other than local (Dropbox, Google Drive, OneDrive, iCloud, URL) are recognised and reported, not resolved.
• Mobile “show in folder” (iOS shareddocuments://, Android content://) has not run: Android and iOS are not configured.
• The shared library is not updated by the app: it is seeded once and then left alone.
• Warnings are not grouped; the manifest warnings join the same list.
• Resolution through official for official files (§6.1 second paragraph) is not implemented; every file resolves from the viewer’s point of view.
• Fountain, SRT, OTIO, timeline export and every §15–16 concern are out of scope so far.
• Media: images are shown; audio and video takes show an icon only.
• Narrow layouts: the window is designed for a desktop width; below about 690 px the split view cannot honour its minimums. The web build is a preview, not a target.
• Spanish is a first translation, not yet reviewed by a native speaker.
• Windows path length limits are not checked before writing a new project folder.
• Warnings are per load and are not persisted or grouped.

---

15. Third-party code

lib/widgets/split_view.dart is adapted from API Dash (lib/widgets/splitview_dashboard.dart, Apache License 2.0, revision 8044b218…). The licence is vendored at third_party/apidash/LICENSE, registered with Flutter’s LicenseRegistry in main.dart, and listed in THIRD_PARTY_NOTICES.md. The rail-beside-sidebar arrangement follows API Dash’s dashboard; the theme, model, tree, views and state are FilmOpen code. FilmOpen’s own licence is not yet decided.

---

Appendix A — File map

filmopen-c/
  README.md                          how to run, layout, languages
  THIRD_PARTY_NOTICES.md
  l10n.yaml                          gen-l10n configuration
  pubspec.yaml, pubspec.lock
  analysis_options.yaml              flutter_lints
  assets/sample/the-cartographer/    the sample project (manifest + 40 JSON files)
  assets/sample/the-cartographer-data/  its media root (9 placeholder takes)
  assets/sample/library/             the seed of the shared library (model, platform, plugin)
  third_party/apidash/LICENSE
  docs/
    FilmOpen-Project-Specification v1.0.md   the format (v1.3 draft inside)
    FilmOpen-Software-Specification v1.0.md  this document
    FilmOpen-Milestone 1.md                  milestone 1: the reader
    FilmOpen-Milestone 2.md                  milestone 2: manifest, media root, library, log, projects
    FilmOpen-Development-Plan-*.md           earlier planning notes
    Pre-commit-improvements.md               the review that compared filmopen-c with filmopen-a
  lib/
    main.dart            log start-up, licence registration, preferences, ProviderScope
    app.dart             MaterialApp: themes, locale, delegates
    theme.dart           buildTheme, AppColors, monospace stack
    consts.dart          app name/version, sample asset path, spec URL
    models/              author, entity_type, stems, entity, project, diagnostics, manifest, short_name, project_kind, epochs
    services/            project_source (+memory), asset_source, asset_disk(_io/_stub), directory_source(_io/_stub),
                         project_loader, project_template, project_writer, app_log, log_file(_io/_stub),
                         app_paths(_io/_stub), reveal(_io/_stub), project_creator(_io/_stub), library_install(_io/_stub)
    providers/           project (+library), settings, localization, browser, app_paths
    tree/                tree_node (TreeNode, TreeModel), selection, tree_builder
    screens/             dashboard, settings_page, browser/{browser_page, tree_pane, new_project_dialog, detail_pane,
                         detail/{project_overview, project_chooser, category_view, entity_detail,
                         batch_detail, other_files_view, tabs/{project_edit, epochs_editor, overview, script,
                         compare, takes, commentary, json}}}
    widgets/             tree_view, split_view, attribute_view, screenplay_view, info_chip, genre_picker,
                         section_card, empty_state, entity_icons, media_image, short_name_field, messages
    l10n/                app_en.arb, app_es.arb, generated app_localizations*.dart, labels.dart, field_labels.dart
    utils/               natural_compare
  test/                  stems, project, fixtures (+fixture_test), directory_source, localization, widget,
                         manifest, library, short_name, app_log, settings, project_creator, project_menu,
                         project_writer, editing
  windows/, web/         platform runners (window title "FilmOpen")

Size at the end of milestone 1: about 5,500 lines of Dart outside generated code, 600 lines of tests, 549 localisation messages per language. At the end of milestone 2: about 7,300 lines, 1,100 lines of tests, 608 messages per language. At the end of milestone 3: about 8,900 lines, 1,600 lines of tests, 693 messages per language.

Appendix B — Glossary of code names

Name	Meaning
stem	a filename without extension, e.g. sc_5_john123_v1
versions key	the stem minus author and version, e.g. ch_main-hero_30yo; what an official pointer names
group key	type and tag only, e.g. ch_main-hero; every epoch and version of one entity
EntityGroup	one entity: all epochs
EntityVersions	one entity at one epoch: all authors’ versions
viewer	the author handle the user browses as; empty means none
resolution	the outcome of looking up a reference: an entity, or a ResolutionProblem
selection	what the detail pane shows; the tree indexes rows by selection keys
wrapper row	the Shots / Cues grouping under a story unit
companion file	a file the grammar names that is not JSON (plugin code)
other file	a file the grammar does not name
manifest	filmopen-project.json: the fixed-name file that identifies a project folder and names its media root
media root	the folder takes and referenced media are read from: the manifest’s data folder, else the project folder
locator	the manifest’s typed “where” ({type, path}) for the media root
library, shared library	the models, platforms and plugins installed beside projects, indexed with every project
origin	whether an entity file came from the project folder or the library
short name	a segment (§5.2) as a person types it: a folder name, a tag, an epoch
pick	the version the viewer prefers: prefer in their own commentary file; a green check in the UI
version label	the header’s label: a short word shown beside the version number in lists
session copy	a project held in memory for one run of the web preview; nothing reaches a disk
default epoch	the first epoch the project declares; where implicit references fall back to
reveal	showing a file in the platform’s file browser with the file selected