@heyo-sh/heyo-cms 0.0.0-stage → 0.2.0

package/dist/types/media.d.ts

@@ -0,0 +1,342 @@
+import type { Actor, OperationSource } from "./actor";
+import type { JsonObject } from "./json";
+import type { StorageAdapter } from "./storage";
+/**
+ * Where a file is in its life (section 6).
+ *
+ * `orphaned` is the state that makes the whole design work: a file that lost
+ * its last reference stops being counted as used but keeps serving, so an
+ * accidental delete or a reverted edit costs nothing for `retention.purgeAfter`.
+ * `purging` is only ever seen by a collector that died mid-sweep.
+ */
+export type MediaStatus = "active" | "orphaned" | "purging";
+/** Relative, `0..1`, origin top-left. Resolution-independent by construction. */
+export interface FocalPoint {
+    x: number;
+    y: number;
+}
+/** A rectangle in the pixels of the stored original. */
+export interface CropRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A file, as everything outside the engine sees it.
+ *
+ * `crop` and `variants` are stored inside the `metadata` column under those
+ * two reserved keys and surfaced here, because a panel needs them and nobody
+ * should have to know they share a column with user metadata.
+ */
+export interface MediaDocument {
+    id: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    width: number | null;
+    height: number | null;
+    storageKey: string;
+    checksum: string | null;
+    /** Localized alternative text, keyed by locale like any content field. */
+    alt: Record<string, string>;
+    focalPoint: FocalPoint | null;
+    crop: CropRect | null;
+    status: MediaStatus;
+    orphanedAt: string | null;
+    /** When the collector will delete it. `null` means never. */
+    purgeAfter: string | null;
+    /** Why the last purge attempt failed, so it is not retried blindly. */
+    purgeError: string | null;
+    /** Everything except the two keys the engine reserves. */
+    metadata: JsonObject;
+    /** Named sizes that exist as stored objects right now. */
+    variants: string[];
+    createdBy: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    /** The public URL of the original, from the storage adapter. */
+    url: string;
+}
+/** One place a document points at a file. */
+export interface MediaUsage {
+    mediaId: string;
+    collection: string;
+    documentId: string;
+    field: string;
+    /** Empty for a field that is not localized. */
+    locale: string;
+    createdAt: string | null;
+}
+/** One file used by one document, as `cms.media.forDocuments()` returns it. */
+export interface MediaDocumentUsage {
+    media: MediaDocument;
+    field: string;
+    /** Null for a field that is not localized: the file is used in every locale. */
+    locale: string | null;
+}
+export interface MediaForDocumentsArgs {
+    /** Only these documents. All of the collection's, by default. */
+    ids?: readonly string[];
+}
+/** The fields of a file a URL is made of. A `MediaDocument` has them all. */
+export type MediaUrlInput = Pick<MediaDocument, "id" | "filename" | "mimeType"> & Partial<Pick<MediaDocument, "width" | "height" | "crop" | "focalPoint">>;
+export type MediaImageInput = MediaUrlInput & Partial<Pick<MediaDocument, "alt">>;
+export interface MediaUrlOptions {
+    /** A name from `uploads.images.variants.sizes`; the original when omitted. */
+    variant?: string;
+}
+export interface MediaSrcsetOptions {
+    /**
+     * The sizes to offer, by name. By default every declared size that keeps
+     * the picture's shape: `inside` and `outside` fits, and one-sided boxes.
+     */
+    sizes?: string[];
+}
+export interface MediaImageOptions {
+    /** One named size as the `src`, without a `srcset`: a thumbnail, a card. */
+    variant?: string;
+    /** The `sizes` attribute that goes with the `srcset`, e.g. `(min-width: 768px) 680px, 100vw`. */
+    sizes?: string;
+    /** The sizes the `srcset` offers; see `MediaSrcsetOptions.sizes`. */
+    srcset?: string[];
+    /** Which language of the library's alt text; the default locale otherwise. */
+    locale?: string;
+}
+/** An `<img>`, as data. Every field maps to the attribute of the same name. */
+export interface MediaImage {
+    src: string;
+    width: number | null;
+    height: number | null;
+    srcset: string | null;
+    sizes: string | null;
+    /** The library's alt text in the requested locale, or null when there is none. */
+    alt: string | null;
+}
+export interface MediaRichTextOptions {
+    /** `html` by default. */
+    format?: "html" | "markdown" | "text";
+    /** Which language of the library's alt text to fall back on. */
+    locale?: string;
+    /** The `sizes` attribute for every image's `srcset`. */
+    sizes?: string;
+    /**
+     * `lazy` by default: images in prose are rarely what a reader sees first.
+     * `eager` for a document whose first image is the largest thing on screen.
+     */
+    loading?: "lazy" | "eager";
+}
+/** What an upload may be handed. All of them end up as bytes. */
+export type MediaSource = Blob | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
+export interface MediaUploadArgs {
+    file: MediaSource;
+    /** Required unless `file` is a `File`, which already carries one. */
+    filename?: string;
+    /** Sniffed from the bytes when absent or when the client sent octet-stream. */
+    contentType?: string;
+    /** A string is stored under `locale`; an object is stored as given. */
+    alt?: string | Record<string, string>;
+    locale?: string;
+    metadata?: JsonObject;
+    actor?: Actor | null;
+    source?: OperationSource;
+}
+export interface MediaListArgs {
+    status?: MediaStatus;
+    /** `image/*` style wildcards allowed. */
+    mimeType?: string;
+    /** Case-insensitive match on the filename. */
+    search?: string;
+    limit?: number;
+    cursor?: string;
+    actor?: Actor | null;
+}
+export interface MediaListResult {
+    docs: MediaDocument[];
+    limit: number;
+    hasNextPage: boolean;
+    cursor: string | null;
+}
+export interface MediaUpdateArgs {
+    id: string;
+    filename?: string;
+    /** A string writes one locale; an object replaces the whole map. */
+    alt?: string | Record<string, string>;
+    locale?: string;
+    /** `null` clears it. Requires `uploads.images.focalPoint`. */
+    focalPoint?: FocalPoint | null;
+    /** `null` clears it. Requires `uploads.images.crop`. */
+    crop?: CropRect | null;
+    /** Merged into the existing metadata; the reserved keys are refused. */
+    metadata?: JsonObject;
+    actor?: Actor | null;
+    source?: OperationSource;
+}
+export interface MediaDeleteArgs {
+    id: string;
+    /**
+     * Deletes a file that documents still point at.
+     *
+     * Without it a referenced file is refused, because "delete" in a media
+     * library is routinely clicked on something that is on a page right now.
+     */
+    force?: boolean;
+    actor?: Actor | null;
+    source?: OperationSource;
+}
+export interface MediaKeepArgs {
+    id: string;
+    actor?: Actor | null;
+    source?: OperationSource;
+}
+export interface MediaVariantArgs {
+    id: string;
+    /**
+     * A name from `uploads.images.variants.sizes`. Omit for the original.
+     *
+     * Only declared names are accepted. Arbitrary dimensions in a URL are a way
+     * to make a stranger fill a bucket and burn CPU, one pixel at a time.
+     */
+    variant?: string;
+    /** Renders again even if a stored copy exists. */
+    refresh?: boolean;
+}
+/**
+ * One answer to "give me this file at this size".
+ *
+ * `cached` says whether the bytes came from storage or were rendered during
+ * this call, which is what makes the on-demand pipeline observable instead of
+ * a guess about CDN behaviour.
+ */
+export interface MediaVariantResult {
+    media: MediaDocument;
+    variant: string | null;
+    key: string;
+    contentType: string;
+    width: number | null;
+    height: number | null;
+    size: number | null;
+    body: ReadableStream;
+    url: string;
+    cached: boolean;
+    /**
+     * Why the named size could not be rendered, when it could not.
+     *
+     * The original is served in its place and nothing is stored, so the next
+     * request tries again — the usual cause is a quota that resets, or a
+     * service that comes back. Null whenever the answer is what was asked for.
+     * An HTTP layer should not cache a fallback for long.
+     */
+    processingError: string | null;
+}
+export interface MediaCollectArgs {
+    /** The moment the sweep runs as. Injectable so a test need not wait. */
+    now?: Date;
+    limit?: number;
+}
+export interface MediaCollectReport {
+    examined: number;
+    purged: number;
+    /** Files that were used again between being orphaned and being collected. */
+    reclaimed: number;
+    failed: number;
+}
+/**
+ * `cms.media`.
+ *
+ * Media is a high-level setting rather than a plugin (section 3), so it is a
+ * first-class part of the instance: the same object the REST routes call in
+ * stage 7 and the panel calls in stage 8, available without HTTP so a seed
+ * script or a migration can upload a file.
+ */
+export interface CmsMedia {
+    upload(args: MediaUploadArgs): Promise<MediaDocument>;
+    list(args?: MediaListArgs): Promise<MediaListResult>;
+    get(id: string): Promise<MediaDocument | null>;
+    update(args: MediaUpdateArgs): Promise<MediaDocument>;
+    /** Removes the record, the original and every stored variant. */
+    delete(args: MediaDeleteArgs): Promise<MediaDocument>;
+    /** The panel's "Keep" button: clears the purge deadline of an orphan. */
+    keep(args: MediaKeepArgs): Promise<MediaDocument>;
+    /** Where a file is used. Empty for an orphan, by definition. */
+    usages(id: string): Promise<MediaUsage[]>;
+    /** The original or a named size, rendering and storing it if needed. */
+    variant(args: MediaVariantArgs): Promise<MediaVariantResult | null>;
+    /** The `media-gc` sweep. Also registered in `cms.jobs`. */
+    collect(args?: MediaCollectArgs): Promise<MediaCollectReport>;
+    /** The configured adapter, built on first use. */
+    storage(): Promise<StorageAdapter>;
+    /**
+     * Several files by id, in one query. Ids that do not exist are absent from
+     * the map rather than an error: a page that references a deleted picture
+     * should lose the picture, not the page.
+     */
+    getMany(ids: readonly string[]): Promise<Map<string, MediaDocument>>;
+    /**
+     * Every file a collection's documents use, per document — read from the
+     * reference count the engine already keeps, so it costs two queries for
+     * the whole collection instead of a parse of every document. What an
+     * image sitemap is built from.
+     */
+    forDocuments(collection: string, args?: MediaForDocumentsArgs): Promise<Map<string, MediaDocumentUsage[]>>;
+    /**
+     * Where a file or one of its sizes is served. Synchronous: it is
+     * arithmetic on the configuration and the record, never a storage call.
+     * Uses `uploads.publicPath` when the deployment has one.
+     */
+    url(media: MediaUrlInput, options?: MediaUrlOptions): string;
+    /** The declared sizes that keep the file's shape, as a `srcset`; null when there is no choice. */
+    srcset(media: MediaUrlInput, options?: MediaSrcsetOptions): string | null;
+    /** `src`, `srcset`, `width`, `height` and `alt` for an `<img>`. */
+    image(media: MediaImageInput, options?: MediaImageOptions): MediaImage;
+    /**
+     * A rich-text value as HTML (or Markdown, or text), with every library
+     * image resolved: its public URL, its dimensions, a `srcset` of the
+     * declared sizes, lazy loading, and the library's alt text where the
+     * editor left the node's empty. One query for all the images.
+     */
+    renderRichText(value: unknown, options?: MediaRichTextOptions): Promise<string>;
+}
+export type ImageFormat = "jpeg" | "png" | "gif" | "webp" | "avif" | "svg" | "tiff";
+/** What the built-in header parser can tell without decoding an image. */
+export interface ImageInfo {
+    format: ImageFormat;
+    contentType: string;
+    width: number;
+    height: number;
+}
+/** One rendering request, in the vocabulary every image library shares. */
+export interface ImageTransform {
+    width?: number;
+    height?: number;
+    fit?: "cover" | "contain" | "inside" | "outside";
+    /** Where `cover` should crop around. Relative, so it survives a resize. */
+    position?: FocalPoint;
+    /** Applied to the original pixels, before any resize. */
+    crop?: CropRect;
+    format?: "webp" | "avif" | "jpeg" | "png";
+    quality?: number;
+    stripMetadata?: boolean;
+}
+export interface ProcessedImage {
+    data: Uint8Array;
+    contentType: string;
+    width: number;
+    height: number;
+}
+/**
+ * The pluggable renderer.
+ *
+ * Deliberately not built in. A codec is either a native module, which has no
+ * place in a package that has to load in a Worker, or a service call, which
+ * has no place in a package that has to run offline. Everything the engine can
+ * do without one — reading dimensions, enforcing limits, stripping EXIF — it
+ * does itself; everything that needs real pixels goes through here.
+ */
+export interface ImageProcessor {
+    /** `sharp`, `cloudflare-images`. Printed by `cms.inspect()`. */
+    readonly id: string;
+    supports(contentType: string): boolean;
+    transform(source: Uint8Array, transform: ImageTransform, info: ImageInfo): Promise<ProcessedImage>;
+}
+//# sourceMappingURL=media.d.ts.map

package/dist/types/media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../src/types/media.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE5D,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,uEAAuE;IACvE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,EAAE,UAAU,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,aAAa,EACb,IAAI,GAAG,UAAU,GAAG,UAAU,CAC/B,GACC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC;AAE3E,MAAM,MAAM,eAAe,GAAG,aAAa,GACzC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kFAAkF;IAClF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IACtC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,iEAAiE;AACjE,MAAM,MAAM,WAAW,GACrB,IAAI,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,wDAAwD;IACxD,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACtD,IAAI,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACrD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACtD,iEAAiE;IACjE,MAAM,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACtD,yEAAyE;IACzE,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAClD,gEAAgE;IAChE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC1C,wEAAwE;IACxE,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACpE,2DAA2D;IAC3D,OAAO,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9D,kDAAkD;IAClD,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACrE;;;;;OAKG;IACH,YAAY,CACV,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,qBAAqB,GAC3B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC;IAC9C;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC;IAC7D,kGAAkG;IAClG,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1E,mEAAmE;IACnE,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAAC;IACvE;;;;;OAKG;IACH,cAAc,CACZ,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAMD,MAAM,MAAM,WAAW,GACrB,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5D,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,yDAAyD;IACzD,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,SAAS,CACP,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B"}

package/dist/types/panel.d.ts

@@ -0,0 +1,249 @@
+import type { EditorSchemaDescription } from "./editor";
+import type { JsonValue } from "./json";
+/**
+ * What the panel is told about this deployment (stage 8).
+ *
+ * The panel is one static bundle serving every configuration, so everything
+ * it renders — which collections exist, which fields they carry, which
+ * languages are registered, whether there is a trash — has to arrive as data.
+ * `GET /panel` is that payload, and this file is its type.
+ *
+ * Two rules decide what may appear here:
+ *
+ * 1. **Only what survives JSON.** An access rule, a `condition` and a hook
+ *    are functions; they stay on the server and the panel is told *that they
+ *    exist* instead of being handed something it cannot run.
+ * 2. **Resolved, not raw.** `purgeAfter: "30d"` is also given in milliseconds
+ *    because a countdown should not re-implement the duration grammar, and a
+ *    locale arrives with the name of its language, because `pl` is not a
+ *    label a switcher can show.
+ */
+/** One entry in the AI menu next to a field. Keys come from `field.ai`. */
+export interface PanelFieldAiAction {
+    key: string;
+    label: string;
+    /** Present when the action overrides `ai.defaultModel`. */
+    model?: {
+        provider: string;
+        model: string;
+    };
+}
+/**
+ * Whether the caller may see and write a field.
+ *
+ * Evaluated with the actor but **without a record**, because the panel asks
+ * before a document is chosen — so a rule that reads `record` answers for the
+ * generic case and the engine remains the authority on the specific one. A
+ * rule that throws without a record counts as permitted here and is still
+ * enforced on the write.
+ */
+export interface PanelAccessFlags {
+    read: boolean;
+    update: boolean;
+}
+export interface PanelField {
+    name: string;
+    type: string;
+    label: string;
+    description?: string;
+    required: boolean;
+    localized: boolean;
+    readOnly: boolean;
+    unique: boolean;
+    /** Server-side deterministic generator is available for this field. */
+    generate: boolean;
+    defaultValue?: JsonValue;
+    /**
+     * The field type's own options, minus everything that is a function.
+     *
+     * `select` carries its choices here, `relation` its target, `media` its
+     * accept list — the panel reads them by field type, exactly as the field
+     * type's `Input` would.
+     */
+    options: Record<string, JsonValue>;
+    admin: {
+        placeholder?: string;
+        hidden: boolean;
+    };
+    ai: PanelFieldAiAction[];
+    access: PanelAccessFlags;
+}
+export interface PanelCollection {
+    name: string;
+    slug: string;
+    label: string;
+    kind: "collection" | "global";
+    group?: string;
+    description?: string;
+    /** Field used as the row title. Resolved here so the panel never guesses. */
+    useAsTitle: string | null;
+    defaultColumns: string[];
+    fields: PanelField[];
+    /**
+     * What this actor may do, evaluated without a record.
+     *
+     * Drives whether the panel offers a "New" button, not whether the write
+     * succeeds: a rule that depends on the document is answered properly by the
+     * engine when the document exists.
+     */
+    can: {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+    };
+}
+export interface PanelLocale {
+    code: string;
+    /** The English name of the language, looked up from the code. */
+    name: string;
+    rtl: boolean;
+    isDefault: boolean;
+}
+/**
+ * The languages, as the switcher needs them.
+ *
+ * Configuration, not a registry: `i18n.locales` is a list of codes, so the
+ * panel renders it and never offers to edit it.
+ */
+export interface PanelI18n {
+    locales: PanelLocale[];
+    defaultLocale: string;
+}
+export interface PanelMedia {
+    enabled: boolean;
+    /** Declared sizes. Nothing else may be requested from a URL. */
+    variants: string[];
+    variantMode: "on-demand" | "pregenerate" | null;
+    focalPoint: boolean;
+    crop: boolean;
+    accept: string[];
+    maxFileSize: string | null;
+    maxFileSizeBytes: number | null;
+    /** How long an unused file keeps serving, for the countdown. */
+    purgeAfter: string | null;
+    purgeAfterMs: number | null;
+}
+export interface PanelTrash {
+    enabled: boolean;
+    purgeAfter: string | null;
+    purgeAfterMs: number | null;
+}
+export interface PanelAuth {
+    methods: string[];
+    twoFactor: boolean;
+    apiKeys: boolean;
+    sso: string | null;
+    /**
+     * Whether the magic-link and password-reset routes exist at all.
+     *
+     * They are registered only when `admin.auth.deliverToken` is configured, so
+     * a sign-in screen that offered them unconditionally would offer a 404.
+     */
+    magicLink: boolean;
+    passwordReset: boolean;
+    /**
+     * Whether this deployment has no account yet.
+     *
+     * `true` turns the sign-in screen into a "claim this CMS" screen: there is
+     * nobody to sign in as, and `POST /auth/setup` is open for exactly as long
+     * as that sentence stays true.
+     */
+    setupRequired: boolean;
+}
+export interface PanelRbac {
+    enabled: boolean;
+    roles: string[];
+    customRoles: boolean;
+}
+/**
+ * AI, as the panel sees it.
+ *
+ * `configured` is "there is an `ai` section"; `runtime` is "something answers
+ * the AI routes". They are still two flags rather than one because they fail
+ * for different reasons — no section, or no credentials for the provider the
+ * default model names — and a greyed-out button with no explanation is a bug
+ * report.
+ */
+export interface PanelAi {
+    configured: boolean;
+    runtime: boolean;
+    defaultModel: {
+        provider: string;
+        model: string;
+    } | null;
+    /**
+     * Whether the panel-wide assistant is switched on for this deployment.
+     *
+     * The composer is rendered either way. A disabled composer that names its
+     * reason is a feature somebody can fix; a composer that is simply not there
+     * is a feature nobody reports as missing.
+     */
+    assistant: boolean;
+    /** Effective assistant settings. Instructions themselves never leave the server. */
+    assistantSettings: {
+        model: {
+            provider: string;
+            model: string;
+        };
+        maxTurns: number;
+        maxToolCalls: number;
+        timeoutMs: number;
+        customInstructions: boolean;
+    } | null;
+    /** Every registered action id, including the ones plugins added. */
+    actions: string[];
+    /** Whether provider keys can be managed from the settings screen. */
+    managedKeys: boolean;
+}
+export interface PanelWebhooks {
+    enabled: boolean;
+    managedInAdmin: boolean;
+    /** Whether the delivery endpoints answer. */
+    runtime: boolean;
+    /** The event catalogue, so the subscription form is a picker. */
+    events: string[];
+}
+/**
+ * A plugin, as the panel can act on it.
+ *
+ * `scripts` is the whole of the client extension story: the panel is one
+ * static bundle compiled before any plugin existed, so a plugin that wants
+ * to render something ships a script the panel loads at boot, and that
+ * script registers a field control or a view against the global the panel
+ * exposes. The alternative — shipping React components through JSON — is not
+ * a thing that can work.
+ */
+export interface PanelPlugin {
+    id: string;
+    navItems: {
+        label: string;
+        path: string;
+        icon?: string;
+    }[];
+    /** URLs, relative to `basePath` unless absolute. Loaded in order. */
+    scripts: string[];
+    /** Field types the plugin says it renders, for a diagnostic when it fails. */
+    fields: string[];
+}
+export interface PanelConfig {
+    title: string;
+    /** Where the API is mounted, absolute: every request the panel makes. */
+    basePath: string;
+    /** Where the panel itself is mounted, absolute: its router's prefix. */
+    panelPath: string;
+    collections: PanelCollection[];
+    globals: PanelCollection[];
+    i18n: PanelI18n;
+    media: PanelMedia;
+    trash: PanelTrash;
+    auth: PanelAuth;
+    rbac: PanelRbac;
+    ai: PanelAi;
+    webhooks: PanelWebhooks;
+    /** Rich-text nodes and marks, including the ones plugins registered. */
+    editor: EditorSchemaDescription;
+    /** Installed plugins and what they contribute to this screen. */
+    plugins: PanelPlugin[];
+}
+//# sourceMappingURL=panel.d.ts.map

package/dist/types/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../../src/types/panel.ts"],"names":[],"mappings":"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"}