@aglyn/aglyn 1.0.0-beta.198 → 1.0.0-beta.199

package/src/lib/app-utils/media-embedded-fields.d.ts

@@ -0,0 +1,471 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The metadata a file carries INSIDE its own bytes (AGL-3331): EXIF, IPTC
+ * and XMP on a photo, the document info of a PDF, the core and custom
+ * properties of an Office file, the tags of a video container.
+ *
+ * ## Why this module is client-safe and the parsers are not
+ *
+ * The parsers and writers live in `media-embedded-metadata/` and are exposed
+ * only through `@aglyn/aglyn/server` — they need `node:zlib` and
+ * `node:crypto`, and nothing in a browser ever holds the bytes they read.
+ * What the console needs is the SHAPE of what they produced (it is stored on
+ * the media document) and the rules for presenting and editing it, which is
+ * everything here. Keeping the two apart keeps a PDF parser out of the
+ * console bundle.
+ *
+ * ## Canonical keys
+ *
+ * A photo's caption can be written in three places at once — XMP
+ * `dc:description`, IPTC 2:120 and EXIF `ImageDescription` — and a PDF's in
+ * two. The reader folds every spelling of one idea into one canonical key
+ * ({@link MEDIA_EMBEDDED_CATALOG}), so the drawer shows ONE "Description"
+ * rather than three rows that may or may not agree, and the writer fans an
+ * edit back out to every place that already holds it (the Metadata Working
+ * Group's rule: never leave a stale copy for the next reader to prefer).
+ *
+ * Anything a file carries that is not in the catalog — an XMP property from
+ * a DAM we have never heard of, a PDF custom property, a PNG text chunk —
+ * still surfaces, under a namespaced "other" key ({@link otherEmbeddedKey})
+ * that round-trips to the writer unchanged.
+ */
+/** Where a value was read from. Several sources can back one field. */
+export type MediaEmbeddedSource = 'xmp' | 'iptc' | 'exif' | 'icc' | 'png' | 'comment' | 'pdf' | 'ooxml' | 'mp4' | 'webm' | 'svg';
+/** How the drawer groups fields, in display order. */
+export type MediaEmbeddedGroup = 'description' | 'rights' | 'location' | 'capture' | 'document' | 'technical' | 'other';
+export declare const MEDIA_EMBEDDED_GROUP_ORDER: readonly MediaEmbeddedGroup[];
+export declare const MEDIA_EMBEDDED_GROUP_LABELS: Record<MediaEmbeddedGroup, string>;
+/**
+ * The container a file was read as. `null`-free: a file whose format has no
+ * reader is simply not given an `embeddedMetadata` record at all.
+ */
+export type MediaEmbeddedFormat = 'jpeg' | 'png' | 'webp' | 'gif' | 'tiff' | 'heif' | 'svg' | 'pdf' | 'ooxml' | 'mp4' | 'webm';
+/**
+ * The formats whose bytes can take an edit without being re-encoded.
+ *
+ * Every writer here rewrites METADATA containers only — JPEG APP segments,
+ * PNG ancillary chunks, WebP RIFF chunks, a TIFF's IFD, a PDF incremental
+ * update, an Office package's property parts — and copies the image data,
+ * page content and every other part through byte for byte. A format that
+ * cannot promise that (a video's `moov` would move its sample offsets; an
+ * SVG is sanitized on every ingress and is its own markup) is read-only.
+ */
+export declare const MEDIA_EMBEDDED_WRITABLE_FORMATS: ReadonlySet<MediaEmbeddedFormat>;
+/** How a value is typed, which decides the editor and the validation. */
+export type MediaEmbeddedValueKind = 'text' | 'longText' | 'list' | 'date' | 'rating' | 'gps';
+export interface MediaEmbeddedCatalogEntry {
+    label: string;
+    group: MediaEmbeddedGroup;
+    kind: MediaEmbeddedValueKind;
+    /**
+     * The formats an edit of this key can be written into. Absent means the
+     * key is read-only everywhere — a measured fact such as an exposure time
+     * or a page count, which describes the bytes rather than annotating them.
+     */
+    writable?: readonly MediaEmbeddedFormat[];
+    /**
+     * `gps` only: the one edit offered is removal. Moving a photo's recorded
+     * location is not a thing anybody needs from a DAM; taking it OFF a photo
+     * before it goes on a public page is.
+     */
+    removeOnly?: boolean;
+    /** Format-specific label, where a format names the idea differently. */
+    labels?: Partial<Record<MediaEmbeddedFormat, string>>;
+    /** Format-specific group — a PDF's creation date is not a camera fact. */
+    groups?: Partial<Record<MediaEmbeddedFormat, MediaEmbeddedGroup>>;
+}
+/**
+ * Every canonical key, in display order within its group.
+ *
+ * ## Value formats every reader and writer agrees on
+ *
+ * - `date`: ISO 8601 — `2021-05-03T10:11:12`, with `Z` or `±HH:MM` only when
+ *   the source recorded a zone (EXIF 2.3's `OffsetTimeOriginal`, a PDF
+ *   date's `+05'00'`). Never invented: a local camera time stays local.
+ * - `list`: an array of strings (creators, keywords).
+ * - `gps`: `"<lat>,<lon>"` in signed decimal degrees, six places.
+ * - `rating`: `"0"`–`"5"`, XMP's scale; `"-1"` is XMP's "rejected".
+ * - technical values are display strings already (`1/250`, `f/2.8`,
+ *   `35 mm`) because nothing edits them.
+ */
+export declare const MEDIA_EMBEDDED_CATALOG: {
+    readonly title: {
+        readonly label: "Title";
+        readonly group: "description";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly headline: {
+        readonly label: "Headline";
+        readonly group: "description";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly description: {
+        readonly label: "Description";
+        readonly group: "description";
+        readonly kind: "longText";
+        readonly writable: readonly MediaEmbeddedFormat[];
+        readonly labels: {
+            readonly pdf: "Subject";
+            readonly ooxml: "Comments";
+        };
+    };
+    readonly subject: {
+        readonly label: "Subject";
+        readonly group: "description";
+        readonly kind: "text";
+        readonly writable: readonly ["ooxml"];
+    };
+    readonly keywords: {
+        readonly label: "Keywords";
+        readonly group: "description";
+        readonly kind: "list";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly category: {
+        readonly label: "Category";
+        readonly group: "description";
+        readonly kind: "text";
+        readonly writable: readonly ["ooxml"];
+    };
+    readonly comment: {
+        readonly label: "Comment";
+        readonly group: "description";
+        readonly kind: "longText";
+        readonly writable: readonly ["png"];
+    };
+    readonly instructions: {
+        readonly label: "Instructions";
+        readonly group: "description";
+        readonly kind: "longText";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly label: {
+        readonly label: "Label";
+        readonly group: "description";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly rating: {
+        readonly label: "Rating";
+        readonly group: "description";
+        readonly kind: "rating";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly creator: {
+        readonly label: "Creator";
+        readonly group: "rights";
+        readonly kind: "list";
+        readonly writable: readonly MediaEmbeddedFormat[];
+        readonly labels: {
+            readonly pdf: "Author";
+            readonly ooxml: "Author";
+        };
+    };
+    readonly copyright: {
+        readonly label: "Copyright";
+        readonly group: "rights";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly credit: {
+        readonly label: "Credit line";
+        readonly group: "rights";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly source: {
+        readonly label: "Source";
+        readonly group: "rights";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly usageTerms: {
+        readonly label: "Usage terms";
+        readonly group: "rights";
+        readonly kind: "longText";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly webStatement: {
+        readonly label: "Copyright info URL";
+        readonly group: "rights";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly city: {
+        readonly label: "City";
+        readonly group: "location";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly state: {
+        readonly label: "State / province";
+        readonly group: "location";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly country: {
+        readonly label: "Country";
+        readonly group: "location";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly gps: {
+        readonly label: "GPS position";
+        readonly group: "location";
+        readonly kind: "gps";
+        readonly writable: readonly MediaEmbeddedFormat[];
+        readonly removeOnly: true;
+    };
+    readonly gpsAltitude: {
+        readonly label: "Altitude";
+        readonly group: "location";
+        readonly kind: "text";
+    };
+    readonly createdAt: {
+        readonly label: "Date taken";
+        readonly group: "capture";
+        readonly kind: "date";
+        readonly writable: readonly MediaEmbeddedFormat[];
+        readonly labels: {
+            readonly pdf: "Created";
+            readonly ooxml: "Created";
+            readonly svg: "Created";
+            readonly mp4: "Recorded";
+            readonly webm: "Recorded";
+        };
+        readonly groups: {
+            readonly pdf: "document";
+            readonly ooxml: "document";
+            readonly svg: "document";
+        };
+    };
+    readonly make: {
+        readonly label: "Camera make";
+        readonly group: "capture";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly model: {
+        readonly label: "Camera model";
+        readonly group: "capture";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly lens: {
+        readonly label: "Lens";
+        readonly group: "capture";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+    };
+    readonly exposure: {
+        readonly label: "Exposure";
+        readonly group: "capture";
+        readonly kind: "text";
+    };
+    readonly aperture: {
+        readonly label: "Aperture";
+        readonly group: "capture";
+        readonly kind: "text";
+    };
+    readonly iso: {
+        readonly label: "ISO";
+        readonly group: "capture";
+        readonly kind: "text";
+    };
+    readonly focalLength: {
+        readonly label: "Focal length";
+        readonly group: "capture";
+        readonly kind: "text";
+    };
+    readonly flash: {
+        readonly label: "Flash";
+        readonly group: "capture";
+        readonly kind: "text";
+    };
+    readonly modifiedAt: {
+        readonly label: "Modified";
+        readonly group: "document";
+        readonly kind: "date";
+    };
+    readonly software: {
+        readonly label: "Software";
+        readonly group: "document";
+        readonly kind: "text";
+        readonly writable: readonly MediaEmbeddedFormat[];
+        readonly labels: {
+            readonly pdf: "Created with";
+            readonly ooxml: "Application";
+        };
+    };
+    readonly producer: {
+        readonly label: "PDF producer";
+        readonly group: "document";
+        readonly kind: "text";
+        readonly writable: readonly ["pdf"];
+    };
+    readonly lastModifiedBy: {
+        readonly label: "Last modified by";
+        readonly group: "document";
+        readonly kind: "text";
+    };
+    readonly company: {
+        readonly label: "Company";
+        readonly group: "document";
+        readonly kind: "text";
+    };
+    readonly pageCount: {
+        readonly label: "Pages";
+        readonly group: "document";
+        readonly kind: "text";
+        readonly labels: {
+            readonly ooxml: "Pages / slides";
+        };
+    };
+    readonly pdfVersion: {
+        readonly label: "PDF version";
+        readonly group: "document";
+        readonly kind: "text";
+    };
+    readonly orientation: {
+        readonly label: "Orientation";
+        readonly group: "technical";
+        readonly kind: "text";
+    };
+    readonly colorProfile: {
+        readonly label: "Color profile";
+        readonly group: "technical";
+        readonly kind: "text";
+    };
+    readonly encoder: {
+        readonly label: "Encoder";
+        readonly group: "technical";
+        readonly kind: "text";
+    };
+};
+export type MediaEmbeddedCanonicalKey = keyof typeof MEDIA_EMBEDDED_CATALOG;
+/**
+ * The namespaces an "other" key can come from. The key round-trips from
+ * reader to writer verbatim, so its only job is to be unambiguous:
+ *
+ * - `xmp|<namespace URI>|<local name>` — a simple XMP property outside the
+ *   catalog. Keyed by URI, not prefix, because two files may bind the same
+ *   namespace to different prefixes and must still produce one key.
+ * - `png|<keyword>` — a PNG `tEXt`/`zTXt`/`iTXt` chunk.
+ * - `pdf|<Name>` — a PDF document-info entry (Acrobat's "Custom" tab).
+ * - `ooxml|<name>` — an Office custom document property.
+ * - `mp4|<atom or freeform name>`, `webm|<TAG>` — video tags, read-only.
+ */
+export type MediaEmbeddedOtherNamespace = 'xmp' | 'png' | 'pdf' | 'ooxml' | 'mp4' | 'webm';
+export declare function otherEmbeddedKey(namespace: MediaEmbeddedOtherNamespace, ...parts: string[]): string;
+export declare function parseOtherEmbeddedKey(key: string): {
+    namespace: MediaEmbeddedOtherNamespace;
+    parts: string[];
+} | null;
+/** One field as stored on the media document and shown in the drawer. */
+export interface MediaEmbeddedField {
+    /** A {@link MediaEmbeddedCanonicalKey} or an {@link otherEmbeddedKey}. */
+    key: string;
+    label: string;
+    group: MediaEmbeddedGroup;
+    /** Single-valued fields. Absent when `values` is set. */
+    value?: string;
+    /** List-valued fields (creators, keywords). */
+    values?: string[];
+    /** Every block the value was found in, strongest first. */
+    sources: MediaEmbeddedSource[];
+    /** Whether the drawer may offer an edit for it on this file. */
+    editable: boolean;
+}
+/**
+ * `embeddedMetadata` on a media document (AGL-3331). Server-written only —
+ * the Firestore rules lock it like every other fact read from the bytes.
+ */
+export interface MediaEmbeddedMetadata {
+    /** Bumped when the reader's output changes shape, so a sweep can re-read. */
+    version: number;
+    format: MediaEmbeddedFormat;
+    fields: MediaEmbeddedField[];
+    /** Whether an edit can be written back into this file at all. */
+    writable: boolean;
+    /** Why not, in a sentence for the drawer, when `writable` is false. */
+    readOnlyReason?: string;
+    /** True when fields were dropped to stay inside the stored caps. */
+    truncated?: boolean;
+    /**
+     * The `contentSha256` of the bytes this was read from. A record whose
+     * digest no longer matches the document's is stale — the file was
+     * replaced by a path that did not re-read it — and is re-read on open.
+     */
+    contentSha256?: string;
+}
+/** The reader's output version. See {@link MediaEmbeddedMetadata.version}. */
+export declare const MEDIA_EMBEDDED_METADATA_VERSION = 1;
+/** Stored caps: one media document must never approach Firestore's 1 MiB. */
+export declare const MEDIA_EMBEDDED_MAX_FIELDS = 150;
+export declare const MEDIA_EMBEDDED_MAX_VALUE_LENGTH = 2000;
+export declare const MEDIA_EMBEDDED_MAX_LIST_ITEMS = 100;
+/** A single keyword or creator; IPTC's own limit for keywords is 64 bytes. */
+export declare const MEDIA_EMBEDDED_MAX_LIST_ITEM_LENGTH = 256;
+/**
+ * An edit to a file's embedded metadata: key → new value, or `null` to
+ * remove it from the file. A list-valued key takes an array.
+ */
+export type MediaEmbeddedPatch = Record<string, string | string[] | null>;
+export declare function isCanonicalEmbeddedKey(key: string): key is MediaEmbeddedCanonicalKey;
+/** The label a key carries on a given format. */
+export declare function embeddedFieldLabel(key: string, format: MediaEmbeddedFormat, fallback?: string): string;
+/** The group a key is shown under on a given format. */
+export declare function embeddedFieldGroup(key: string, format: MediaEmbeddedFormat): MediaEmbeddedGroup;
+/** How a key's value is edited. Other keys are free text. */
+export declare function embeddedFieldKind(key: string): MediaEmbeddedValueKind;
+/**
+ * Whether an edit of `key` can be written into a file of `format`.
+ *
+ * The one place the answer lives: the reader stamps `editable` with it, the
+ * drawer offers the "add a field" choices from it, and the write route
+ * refuses anything it says no to — so the three cannot disagree about which
+ * fields a JPEG can take.
+ */
+export declare function embeddedKeyWritable(key: string, format: MediaEmbeddedFormat): boolean;
+/**
+ * The canonical keys a file of this format can take, whether or not it
+ * holds them yet — what the drawer offers under "Add a field".
+ */
+export declare function embeddedWritableKeys(format: MediaEmbeddedFormat): MediaEmbeddedCanonicalKey[];
+/**
+ * Validate an edit before it reaches a writer, or say why it cannot.
+ *
+ * Runs in the drawer (to explain) and in the write route (to refuse), so
+ * the messages are written for the person who typed the value.
+ */
+export declare function sanitizeEmbeddedPatch(format: MediaEmbeddedFormat, patch: unknown): {
+    patch: MediaEmbeddedPatch;
+} | {
+    error: string;
+};
+/** The value of a field as one line of text. */
+export declare function embeddedFieldText(field: MediaEmbeddedField): string;
+export declare function embeddedMetadataReadable(contentType: unknown): boolean;
+/**
+ * A field's value as the drawer shows it — the stored value is the
+ * machine form every writer agrees on, and this is the only place it is
+ * dressed for a person.
+ */
+export declare function embeddedFieldDisplay(field: Pick<MediaEmbeddedField, 'key' | 'value' | 'values'>, locale?: string): string;