filmopen_comps

A snapshot

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

Prepare a comp — a standalone comparison of renders — from caller JSON and local originals, then publish its immutable bundle through the comps publishing contract /v1 (packages/comps/openapi/publishing.yaml in filmopen-web, summarized in this package’s PUBLISHING.md). Its request and receipt examples are test/fixtures/comps-examples.json, the same bytes as filmopen-web’s copy, pinned by the same SHA-256. The package has no widgets, project writer or direct account dependency, and initializes nothing at startup.

pure Dart. 11 files, 2,492 lines under lib/; 134 tests in 9 files. Barrel: lib/filmopen_comps.dart.

Depends on

Nothing of FilmOpen. Third-party: archive, crypto, http, image.

Used by

filmopen_app

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

• class CompsArtifact — One immutable artifact’s exact upload identity.
  • CompsArtifact({required this.path, required this.bytes, required this.sha256, required this.contentType}) — Validates a safe path, nonempty byte count, digest and MIME type.
  • final String path — Local hash-based artifact path, never a user’s private path.
  • final int bytes — Exact artifact byte count.
  • final String sha256 — Lowercase SHA-256 digest.
  • final String contentType — Exact content type used by staging and eventual publication.
  • Map<String, Object?> toJson() — Serializes this artifact into an upload inventory.
• class CompsPreparedBundle — A prepared immutable revision retained for retry without regenerating media.
  • final String revision — Unique revision reused for every retry and completion.
  • final String project — The project’s tag, the second segment of the comp’s public address.
  • final String slug — The unguessable last segment of the comp’s public address.
  • final CompsWorkspace workspace — Owned local bytes, disposed by the caller after successful staging or abandonment.
  • final Map<String, Object?> manifest — Deeply immutable uploaded comp.json, including the user-selected title and details.
  • final List<CompsArtifact> files — Exact immutable inventory: comp.json first, then the media and their previews.
  • int get totalBytes — Total upload size including original bytes and previews.
  • String get digest — The contract’s bundle digest: SHA-256 of the compact inventory [[path, bytes, sha256, contentType], …].
  • Map<String, Object?> toUploadJson() — Copies the bounded begin-upload request without tokens or private paths.
  • Future<void> verify({CompsCancellation? cancellation}) — Rechecks every local artifact before any network action.
  • Future<void> dispose() — Releases only the package’s owned local preparation workspace.
• class CompsAssembler — Prepares local originals and caller JSON without any network side effect.
  • CompsAssembler({required this.mediaPreparer, this.limits = const CompsLimits(), this.onEvent}) — Creates an assembler with explicit media tools, product limits and an optional event sink.
  • final CompsMediaPreparer mediaPreparer — Platform-specific preview and measurement strategy.
  • final CompsLimits limits — Product ceilings, optionally tightened by the application.
  • final CompsEventSink? onEvent — Receives each preparation stage with the values it worked on, and a refusal with its cause.
  • Future<CompsPreparedBundle> prepareJson(Map<String, Object?> json, { required Map<String, CompsSource> sources, required CompsWorkspace workspace,… — Validates caller JSON and assembles a revision of [project] inside a fresh workspace.

lib/src/bytes.dart

• class CompsSource — A repeatable local byte capability kept separate from public JSON.
  • String get originalName — The original filename without its private directory.
  • Future<int> length() — Reads the current source byte count.
  • Stream<List<int>> open() — Opens the local original without fetching a remote URL.
• class CompsStoredBytes — The digest and count of bytes retained in a preparation workspace.
  • const CompsStoredBytes(this.bytes, this.sha256) — Creates measured byte facts.
  • final int bytes — Exact retained byte count.
  • final String sha256 — Lowercase SHA-256 digest of the retained bytes.
• class CompsWorkspace — An owned workspace for an immutable comparison bundle.
  • String? get directory — Its local directory, or null for an in-memory workspace.
  • Future<CompsStoredBytes> write(String path, Stream<List<int>> bytes, { required int maxBytes, CompsCancellation? cancellation, }) — Writes a new owned artifact, refusing an existing path and excess bytes.
  • Stream<List<int>> open(String path) — Opens an artifact kept in this workspace.
  • Future<Uint8List> read(String path, {required int maxBytes}) — Reads a bounded owned artifact.
  • Future<void> move(String from, String to) — Moves an owned temporary artifact without overwriting another artifact.
  • Future<bool> contains(String path) — Whether an owned artifact already exists.
  • Future<void> remove(String path) — Removes an owned temporary artifact.
  • Future<void> dispose() — Releases only this workspace’s temporary directory or retained memory.
• function bool safeCompsArtifactPath(String path) — Whether a path names a permitted artifact inside a comp workspace.
• function Future<Uint8List> readCompsBytes(Stream<List<int>> stream, { required int maxBytes, CompsCancellation? cancellation, }) — Reads a stream with a strict byte bound and cancellation checkpoints.
• class CompsMemoryWorkspace — A private in-memory workspace for small bundles and platform adapters.
  • CompsMemoryWorkspace() — Creates a fresh empty workspace owned exclusively by one prepared bundle.
• function Stream<List<int>> cancellableCompsStream(Stream<List<int>> stream, CompsCancellation? cancellation) — Cancels an owned read even when its source has stopped yielding chunks.

lib/src/files_stub.dart

• function CompsSource compsFileSource(String path) — Creates a native file source where local file access is available.
• function Future<CompsWorkspace> createCompsFileWorkspace({String? parent}) — Creates a new native temporary workspace where local file access is available.

lib/src/json_validation.dart — only CompsException

• class CompsException — A preparation or publishing failure: a stable code, and for a service’s answer its status and body.
  • const CompsException(this.code, {this.status, this.detail}) — Creates a failure from a diagnostic code, with the service’s [status] and [detail] where it answered.
  • final String code — The diagnostic code that the caller may translate into a message: the service’s own for a refusal.
  • final int? status — The HTTP status of the service’s answer, where the failure is one.
  • final String? detail — The service’s answer, the first 32 KiB of its body as text, for the caller’s log (§6.17).

lib/src/media.dart

• class CompsMediaPreparation — Measured original facts and a separately generated JPEG preview.
  • CompsMediaPreparation({Uint8List? previewJpeg, this.width, this.height, this.duration}) — Copies a preview while retaining only measured original facts.
  • Uint8List? get previewJpeg — A defensive copy of the generated JPEG preview, or null for audio.
  • final int? width — Measured original width, or null when this adapter cannot measure it.
  • final int? height — Measured original height, or null when this adapter cannot measure it.
  • final num? duration — Measured original duration in seconds, or null when unknown.
• class CompsMediaPreparer — A local adapter that measures originals and generates separate previews.
  • Future<CompsMediaPreparation> prepare({ required CompsMediaDraft media, required CompsWorkspace workspace, required String originalPath, required C… — Prepares one owned original without changing its bytes.
• class PortableCompsMediaPreparer — Portable still-image and WAV preparation without a native process.
  • const PortableCompsMediaPreparer() — Creates the portable preparation adapter.

lib/src/models.dart

• enum CompsVisibility — Whether an approved comp participates in the public monthly directory.
  • values: listed, unlisted
• enum CompsMediaKind — The original media format that a comp card represents.
  • values: image, video, audio
• class CompsPrice — A caller-supplied cost in one explicitly named currency.
  • factory CompsPrice.fromJson(Map<String, Object?> json) — Validates a finite nonnegative amount and an uppercase currency code.
  • final num amount — The supplied cost, including an explicitly supplied zero.
  • final String currency — The three-letter uppercase currency code.
  • Map<String, Object?> toJson() — Copies the supplied amount and currency into a JSON object.
• class CompsMediaDraft — Validated JSON metadata for one caller-selected original.
  • factory CompsMediaDraft.fromJson(Map<String, Object?> json) — Validates caller metadata without deriving facts from a filename.
  • final String id — The safe identifier unique within this comp.
  • final String source — The opaque identifier of the caller’s separate original-byte source.
  • final CompsMediaKind kind — The caller-declared media kind.
  • final String? label — The caller’s display label, or null when unknown.
  • final String? provider — The supplied provider name, or null when unknown.
  • final String? model — The supplied model name, or null when unknown.
  • final String? plugin — The supplied plugin name, or null when unknown.
  • final String? stack — The supplied stack label, or null when unknown.
  • final CompsPrice? price — The supplied monetary cost, or null when unknown.
  • final num? renderSeconds — The supplied render duration in seconds, or null when unknown.
  • final String? prompt — The supplied generation prompt, or null when unknown.
  • final String? generationType — The supplied generation type, or null when unknown.
  • final int? width — The caller’s original width in pixels, or null when unknown.
  • final int? height — The caller’s original height in pixels, or null when unknown.
  • final num? duration — The caller’s media duration in seconds, or null when unknown.
  • final Map<String, Object?>? details — A deeply immutable snapshot of caller extensions, or null when absent.
  • Map<String, Object?> toJson() — Copies normalized metadata into an independently mutable JSON object.
• class CompsDraft — An immutable comp request containing general information and all media metadata.
  • factory CompsDraft.fromJson(Map<String, Object?> json, {DateTime? now}) — Validates and snapshots a bounded caller JSON request.
  • final String name — The user-picked comp name, or the UTC default when omitted.
  • final String description — The supplied general description, empty when omitted.
  • final String? generationType — The supplied comp generation type, or null when unknown.
  • final String? prompt — The supplied general generation prompt, or null when unknown.
  • final CompsVisibility visibility — Whether an approved comp can appear in the public directory.
  • final Map<String, Object?>? details — A deeply immutable snapshot of general extensions, or null when absent.
  • final List<CompsMediaDraft> media — Immutable media metadata in the caller’s original order.
  • Map<String, Object?> toJson() — Copies the normalized request and extensions into mutable JSON values.
• function String defaultCompsName(DateTime now, [String? generationType]) — Builds the UTC timestamp default name with the supplied generation type.

lib/src/publisher.dart

• typedef typedef CompsAccessToken — Retrieves a fresh FilmOpen account bearer only when an upload request is made.
• enum CompsUploadState — The states of a revision.
  • values: receiving, published, cancelled
• class CompsUploadReceipt — An immutable receipt of one revision, which never carries authorization.
  • final String revision — The prepared revision reused by interrupted upload retries.
  • final String bundleDigest — The exact inventory digest confirmed by the service.
  • final CompsUploadState state — Whether the revision is receiving, published or cancelled.
  • final DateTime? expiresAt — The staging expiry of a receiving or cancelled revision; null once published.
  • final List<int> uploaded — Inventory indices the service has confirmed; empty once a published revision’s staged bytes expired.
  • final String? url — The comp’s public address, set when published.
  • final DateTime? publishedAt — When the revision was published, set when published.
  • final String? publicManifestSha256 — The digest of the public comp.json the server wrote, set when published.
• class CompsPublisher — Sends immutable bundles to the comps publishing service’s /v1 routes.
  • CompsPublisher({ required this.client, required this.host, required this.accessToken, this.requestTimeout = const Duration(seconds: 120), this.maxA… — Injects a caller-owned HTTP client, the service’s [host] and the account’s fresh-token callback.
  • final http.Client client — Caller-owned transport, never closed or shared-client-aborted by the package.
  • final String host — The publishing service’s host name, reached over HTTPS alone.
  • final CompsAccessToken accessToken — Supplies the fresh account bearer, never persisted or included in artifacts.
  • final Duration requestTimeout — Maximum time for one token retrieval or authenticated HTTP exchange.
  • final int maxAttempts — Maximum same-revision attempts after a transient transport failure.
  • final CompsEventSink? onEvent — Receives every request before its bearer is attached, every answer, retry, refresh and outcome.
  • Future<CompsUploadReceipt> publish(CompsPreparedBundle bundle, { CompsCancellation? cancellation, void Function(CompsProgress progress)? onProgress… — Verifies bytes, uploads missing artifacts and completes the revision into its published receipt.
  • Future<CompsUploadReceipt> statusOf(String revision, { CompsPreparedBundle? bundle, CompsCancellation? cancellation, }) — Reads the state of [revision], with no prepared bundle needed: a published revision answers its kept receipt at any later time.
  • Future<CompsUploadReceipt> status(CompsPreparedBundle bundle, {CompsCancellation? cancellation}) — [statusOf] the [bundle]’s revision, checked against the bundle.
  • Future<CompsUploadReceipt> cancel(String revision, {CompsPreparedBundle? bundle}) — Cancels [revision]’s staging without touching local originals, with no prepared bundle needed.

lib/src/runtime.dart

• typedef typedef CompsEvent — One step of preparing or publishing, as a name and the values it worked on (§6.17).
• typedef typedef CompsEventSink — Receives every [CompsEvent] of an assembler or a publisher.
• enum CompsPhase — The phase of preparing or staging a comparison.
  • values: preparing, uploading, published
• class CompsLimits — Product limits shared with the private publishing service.
  • const CompsLimits({ this.maxOriginalBytes = 64 * 1024 * 1024, this.maxTotalBytes = 512 * 1024 * 1024, this.maxItems = 128, this.maxManifestBytes =… — Creates limits which may be tightened by a caller.
  • void validate() — Refuses limits which would relax a private-service ceiling.
  • final int maxOriginalBytes — Maximum bytes in one untouched original.
  • final int maxTotalBytes — Maximum bytes in the entire bundle.
  • final int maxItems — Maximum original media entries.
  • final int maxManifestBytes — Maximum UTF-8 bytes in comp.json.
  • final int maxPreviewBytes — Maximum bytes in a generated JPEG preview.
  • final int maxImagePixels — Maximum pixels decoded to prepare an image preview.
• class CompsCancellation — A caller-owned cancellation signal which carries no private data.
  • bool get isCancelled — Whether cancellation has been requested.
  • Future<void> get whenCancelled — Completes when an active request should be aborted.
  • void cancel() — Requests cancellation once.
  • Future<T> wait<T>(Future<T> action) — Stops waiting on a caller future when cancelled, observing any late error.
  • void check() — Refuses the next checkpoint after cancellation.
• class CompsProgress — Byte and file progress containing no tokens, paths or content.
  • const CompsProgress(this.phase, { required this.completedBytes, required this.totalBytes, required this.completedFiles, required this.totalFiles, }) — Creates an immutable progress event.
  • final CompsPhase phase — Current preparation or staging phase.
  • final int completedBytes — Bytes prepared or confirmed uploaded.
  • final int? totalBytes — Total known bytes, or null while preparing.
  • final int completedFiles — Number of completed original entries or uploaded files.
  • final int totalFiles — Number of original entries or bundle files.

Internal

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

• lib/src/files_io.dart: compsFileSource, _FileSource, createCompsFileWorkspace, _HashSink, _FileWorkspace