@plumix/plugin-media 0.1.0 → 0.3.0

package/dist/builder.d.ts

@@ -1,80 +1,116 @@
-import type { MediaListMetaBoxField, MediaMetaBoxField, MetaBoxFieldSpan } from "plumix/plugin";
+import type { Label } from "plumix/i18n";
+import type { FieldBuilder, MediaListMetaBoxField, MediaMetaBoxField, MetaBoxFieldSpan, MetaBoxFieldValidate, MetaFieldCondition, MetaFieldConditionRule } from "plumix/plugin";
+import type { MediaFieldScope, MediaReference } from "./lookup.js";
+/** One read element: the hydrated `MediaReference`, or the bare id after `.returns("id")`. */
+type MediaReadItem<Returns extends "id" | "hydrated"> = Returns extends "id" ? string : MediaReference;
 /**
- * Per-field options for the `media()` builder.
- *
- * `accept` filters the picker grid client-side (UX hint) AND the
- * `mediaLookupAdapter`'s `list({ ids })` path on the server (security
- * boundary — re-validated at write time). Format: a single MIME prefix
- * string (`"image/"` matches every `image/*` mime) OR a readonly array
- * of exact MIME matches (`["image/png", "application/pdf"]`).
- *
- * `default` is a `MediaValue` shape (`{ id, ... }`) — the meta pipeline
- * normalizes the cached fields on every write, so a new entry with a
- * `default: { id: "42" }` ships with the canonical `{ id, mime,
- * filename }` after the first save.
+ * The phantom read type. A single reference is always optional (a
+ * target can be deleted after the id is written); a multi reference
+ * reads a dense array, present once `.required()` guarantees a write.
  */
-export interface MediaFieldOptions {
-    readonly key: string;
-    readonly label: string;
-    readonly required?: boolean;
-    readonly description?: string;
-    readonly default?: MediaValue;
+type MediaReadValue<Multiple extends boolean, Required extends boolean, Returns extends "id" | "hydrated"> = Multiple extends true ? Required extends true ? readonly MediaReadItem<Returns>[] : readonly MediaReadItem<Returns>[] | undefined : MediaReadItem<Returns> | undefined;
+/** The phantom stored shape — bare ids; `.required()` narrows optionality. */
+type MediaStoredValue<Multiple extends boolean, Required extends boolean> = Multiple extends true ? Required extends true ? readonly string[] : readonly string[] | undefined : Required extends true ? string : string | undefined;
+interface MediaFieldState {
+    readonly visibleWhen?: MetaFieldCondition;
+    readonly label?: Label;
+    readonly description?: Label;
+    readonly default?: string | readonly string[];
+    readonly required?: true;
+    readonly multiple?: true;
+    readonly returns?: "id";
+    readonly max?: number;
     readonly span?: MetaBoxFieldSpan;
-    readonly accept?: string | readonly string[];
-}
-/**
- * Storage shape for a single `media` field. The meta pipeline writes
- * `{ id, ...adapterCached }` on every save (mime + filename today;
- * width/height/etc once the upload pipeline captures them). Renders
- * read straight from this object — no `lookup.resolve` per field.
- */
-export interface MediaValue {
-    readonly id: string;
-    readonly mime?: string;
-    readonly filename?: string;
+    readonly capability?: string;
+    readonly showInApi?: true;
+    readonly sanitize?: (value: unknown) => unknown;
+    readonly validate?: MetaBoxFieldValidate;
 }
 /**
- * Build a typed `media` reference field. Stored as a `MediaValue`
- * object — admin thumbnails render without a resolve round-trip, the
- * meta pipeline rewrites the cached fields on every write so the
- * snapshot stays close to the asset.
+ * Fluent chain for the `media` reference field —
+ * `media("hero").accept("image/")`. Mirrors the core reference
+ * builders (`entry` / `term` / `user`): `.accept()` refines the picker
+ * MIME filter, `.multiple()` flips to an id array, `.returns("id")`
+ * opts out of read-time hydration. Immutable — every call returns a
+ * fresh instance.
  *
- * The picker opens the existing Media Library in modal/picker mode,
- * filters the grid to MIME `accept` if set, and emits the bare id +
- * cached fields back to the form on selection.
- *
- * Single-value only — `mediaList()` covers the multi case (slice
- * #132).
- */
-export declare function media(options: MediaFieldOptions): MediaMetaBoxField;
-/**
- * Per-field options for the `mediaList()` builder. Multi-value
- * counterpart to `media()` — same `accept` semantics, plus a `max`
- * length cap. Storage is `MediaValue[]`.
+ * Storage is the bare media id (an id array under `.multiple()`); reads
+ * hydrate to the {@link MediaReference} summary by default so themes
+ * render a media field (URL included) without a manual fetch.
  */
-export interface MediaListFieldOptions {
-    readonly key: string;
-    readonly label: string;
-    readonly required?: boolean;
-    readonly description?: string;
-    readonly default?: readonly MediaValue[];
-    readonly span?: MetaBoxFieldSpan;
-    readonly accept?: string | readonly string[];
-    /** Max items allowed in the array. Omitted = unbounded. */
-    readonly max?: number;
+export declare class MediaFieldBuilder<K extends string = string, Multiple extends boolean = false, Required extends boolean = false, Returns extends "id" | "hydrated" = "hydrated"> implements FieldBuilder {
+    #private;
+    /** Phantom literal key of the field — type-level only, never assigned. */
+    readonly _key: K;
+    /** Phantom read type — hydrated `MediaReference` by default, id after `.returns("id")`. */
+    readonly _value: MediaReadValue<Multiple, Required, Returns>;
+    /** Phantom stored shape — bare ids; `.required()` narrows optionality. */
+    readonly _stored: MediaStoredValue<Multiple, Required>;
+    /** Phantom cardinality marker backing the compile-time gate on `.multiple()` / `.max()`. */
+    readonly _multiple: Multiple;
+    constructor(key: string, scope?: MediaFieldScope, state?: MediaFieldState);
+    /**
+     * Filter the picker (and re-validate on write) by MIME. A single
+     * prefix string (`"image/"` matches every `image/*`) or a readonly
+     * array of exact MIME matches (`["image/png", "application/pdf"]`).
+     */
+    accept(accept: string | readonly string[]): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /**
+     * Store an array of ids instead of a single one — reads become a
+     * dense array. Declare cardinality before `.required()` narrows the
+     * shapes; the `this`-type gate blocks a post-narrowing `.multiple()`.
+     */
+    multiple(this: MediaFieldBuilder<K, false, false, Returns>): MediaFieldBuilder<K, true, false, Returns>;
+    /** Cap the array length — multi-value fields only. */
+    max(this: MediaFieldBuilder<K, true, Required, Returns>, max: number): MediaFieldBuilder<K, true, Required, Returns>;
+    /** Read the bare stored id(s) instead of the hydrated summary. */
+    returns(shape: "id"): MediaFieldBuilder<K, Multiple, Required, "id">;
+    /** Mark the field required — enforced at write time by the constraint walker. */
+    required(): MediaFieldBuilder<K, Multiple, true, Returns>;
+    /** Override the derived (humanized-key) label. */
+    label(label: Label): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Help text rendered under the label. */
+    description(description: Label): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Prefill for absent keys — a stored id (or id array for multi fields). */
+    default(value: Multiple extends true ? readonly string[] : string): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Column span within the box's 12-column grid — a universal layout hint. */
+    span(span: MetaBoxFieldSpan): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Capability gate for this field — see `MetaBoxFieldBase.capability`. */
+    capability(capability: string): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Opt this field's value into public REST responses (default-deny). */
+    showInApi(): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Rule factory: this field's stored id equals `value`. */
+    is(value: string): MetaFieldConditionRule;
+    /** Rule factory: this field's stored id differs from `value`. */
+    isNot(value: string): MetaFieldConditionRule;
+    /** Rule factory: this field has no value (unset or cleared). */
+    isEmpty(): MetaFieldConditionRule;
+    /** Rule factory: this field has a value. */
+    isNotEmpty(): MetaFieldConditionRule;
+    /** Rule factory: the selection includes `id` — multi-value only. */
+    contains(this: MediaFieldBuilder<K, true, Required, Returns>, id: string): MetaFieldConditionRule;
+    /** Rule factory: the selection does not include `id` — multi-value only. */
+    notContains(this: MediaFieldBuilder<K, true, Required, Returns>, id: string): MetaFieldConditionRule;
+    /**
+     * Show this field only when every rule passes (one AND group).
+     * Replaces any previously declared condition; `.orVisibleWhen()`
+     * adds alternatives.
+     */
+    visibleWhen(...rules: MetaFieldConditionRule[]): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Add an OR alternative — one more AND group of rules. */
+    orVisibleWhen(...rules: MetaFieldConditionRule[]): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Normalising transform, applied after coercion and before persistence. */
+    sanitize(sanitize: (value: unknown) => unknown): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Custom validation — `true` for valid, or an i18n-able failure message. */
+    validate(validate: MetaBoxFieldValidate): MediaFieldBuilder<K, Multiple, Required, Returns>;
+    /** Compile the chain into the wire/manifest field definition. */
+    build(): Multiple extends true ? MediaListMetaBoxField : MediaMetaBoxField;
 }
 /**
- * Build a typed `mediaList` reference field — the multi-value
- * counterpart to `media()`. Storage is `MediaValue[]` —
- * `[{ id, mime?, filename? }, ...]`. The meta pipeline rewrites
- * each entry's cached fields on every write so reads can render
- * thumbnails without a per-item resolve round-trip.
- *
- * Picker stays open across selections (so authors can pick several
- * without re-opening) and auto-stops when `max` is reached.
- * Selected items render as a vertical list with up/down reorder
- * and per-item removal; drag-reorder is deferred to a follow-up
- * (see `MediaListPickerField`).
+ * Build a typed `media` reference field — `media("hero")`. The picker
+ * opens the Media Library in modal mode; `.accept()` filters the grid
+ * (and re-validates on write), `.multiple()` stores an id array.
  */
-export declare function mediaList(options: MediaListFieldOptions): MediaListMetaBoxField;
+export declare function media<K extends string>(key: K): MediaFieldBuilder<K>;
+export {};
 //# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAanE;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC7C,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,CAmBvB"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/builder.js

@@ -1,61 +1,161 @@
+var _a;
+// "heroImage" → "Hero image". Derived default for fields authored
+// without `.label()`. Kept local — the plugin can't reach core's
+// private `humanizeFieldKey`, and the rule is a one-liner.
+function humanizeFieldKey(key) {
+    const spaced = key
+        .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replaceAll(/[_:-]+/g, " ")
+        .trim()
+        .toLowerCase();
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
 /**
- * Build a typed `media` reference field. Stored as a `MediaValue`
- * object — admin thumbnails render without a resolve round-trip, the
- * meta pipeline rewrites the cached fields on every write so the
- * snapshot stays close to the asset.
- *
- * The picker opens the existing Media Library in modal/picker mode,
- * filters the grid to MIME `accept` if set, and emits the bare id +
- * cached fields back to the form on selection.
+ * Fluent chain for the `media` reference field —
+ * `media("hero").accept("image/")`. Mirrors the core reference
+ * builders (`entry` / `term` / `user`): `.accept()` refines the picker
+ * MIME filter, `.multiple()` flips to an id array, `.returns("id")`
+ * opts out of read-time hydration. Immutable — every call returns a
+ * fresh instance.
  *
- * Single-value only — `mediaList()` covers the multi case (slice
- * #132).
+ * Storage is the bare media id (an id array under `.multiple()`); reads
+ * hydrate to the {@link MediaReference} summary by default so themes
+ * render a media field (URL included) without a manual fetch.
  */
-export function media(options) {
-    const scope = { accept: options.accept };
-    return {
-        key: options.key,
-        label: options.label,
-        type: "json",
-        inputType: "media",
-        referenceTarget: { kind: "media", scope, valueShape: "object" },
-        required: options.required,
-        description: options.description,
-        default: options.default,
-        span: options.span,
-    };
+export class MediaFieldBuilder {
+    #key;
+    #scope;
+    #state;
+    constructor(key, scope = {}, state = {}) {
+        this.#key = key;
+        this.#scope = scope;
+        this.#state = state;
+    }
+    #fork(patch, scope = this.#scope) {
+        return new _a(this.#key, scope, { ...this.#state, ...patch });
+    }
+    /**
+     * Filter the picker (and re-validate on write) by MIME. A single
+     * prefix string (`"image/"` matches every `image/*`) or a readonly
+     * array of exact MIME matches (`["image/png", "application/pdf"]`).
+     */
+    accept(accept) {
+        return this.#fork({}, { accept });
+    }
+    /**
+     * Store an array of ids instead of a single one — reads become a
+     * dense array. Declare cardinality before `.required()` narrows the
+     * shapes; the `this`-type gate blocks a post-narrowing `.multiple()`.
+     */
+    multiple() {
+        return this.#fork({ multiple: true });
+    }
+    /** Cap the array length — multi-value fields only. */
+    max(max) {
+        return this.#fork({ max });
+    }
+    /** Read the bare stored id(s) instead of the hydrated summary. */
+    returns(shape) {
+        return this.#fork({ returns: shape });
+    }
+    /** Mark the field required — enforced at write time by the constraint walker. */
+    required() {
+        return this.#fork({ required: true });
+    }
+    /** Override the derived (humanized-key) label. */
+    label(label) {
+        return this.#fork({ label });
+    }
+    /** Help text rendered under the label. */
+    description(description) {
+        return this.#fork({ description });
+    }
+    /** Prefill for absent keys — a stored id (or id array for multi fields). */
+    default(value) {
+        return this.#fork({ default: value });
+    }
+    /** Column span within the box's 12-column grid — a universal layout hint. */
+    span(span) {
+        return this.#fork({ span });
+    }
+    /** Capability gate for this field — see `MetaBoxFieldBase.capability`. */
+    capability(capability) {
+        return this.#fork({ capability });
+    }
+    /** Opt this field's value into public REST responses (default-deny). */
+    showInApi() {
+        return this.#fork({ showInApi: true });
+    }
+    /** Rule factory: this field's stored id equals `value`. */
+    is(value) {
+        return { key: this.#key, op: "eq", value };
+    }
+    /** Rule factory: this field's stored id differs from `value`. */
+    isNot(value) {
+        return { key: this.#key, op: "neq", value };
+    }
+    /** Rule factory: this field has no value (unset or cleared). */
+    isEmpty() {
+        return { key: this.#key, op: "empty" };
+    }
+    /** Rule factory: this field has a value. */
+    isNotEmpty() {
+        return { key: this.#key, op: "not_empty" };
+    }
+    /** Rule factory: the selection includes `id` — multi-value only. */
+    contains(id) {
+        return { key: this.#key, op: "contains", value: id };
+    }
+    /** Rule factory: the selection does not include `id` — multi-value only. */
+    notContains(id) {
+        return { key: this.#key, op: "not_contains", value: id };
+    }
+    /**
+     * Show this field only when every rule passes (one AND group).
+     * Replaces any previously declared condition; `.orVisibleWhen()`
+     * adds alternatives.
+     */
+    visibleWhen(...rules) {
+        return this.#fork({ visibleWhen: [rules] });
+    }
+    /** Add an OR alternative — one more AND group of rules. */
+    orVisibleWhen(...rules) {
+        return this.#fork({
+            visibleWhen: [...(this.#state.visibleWhen ?? []), rules],
+        });
+    }
+    /** Normalising transform, applied after coercion and before persistence. */
+    sanitize(sanitize) {
+        return this.#fork({ sanitize });
+    }
+    /** Custom validation — `true` for valid, or an i18n-able failure message. */
+    validate(validate) {
+        return this.#fork({ validate });
+    }
+    /** Compile the chain into the wire/manifest field definition. */
+    build() {
+        const { multiple, ...state } = this.#state;
+        const target = multiple
+            ? { kind: "media", scope: this.#scope, multiple: true }
+            : { kind: "media", scope: this.#scope };
+        const field = {
+            ...state,
+            key: this.#key,
+            label: state.label ?? humanizeFieldKey(this.#key),
+            type: "json",
+            inputType: multiple ? "mediaList" : "media",
+            referenceTarget: target,
+        };
+        return field;
+    }
 }
+_a = MediaFieldBuilder;
 /**
- * Build a typed `mediaList` reference field — the multi-value
- * counterpart to `media()`. Storage is `MediaValue[]` —
- * `[{ id, mime?, filename? }, ...]`. The meta pipeline rewrites
- * each entry's cached fields on every write so reads can render
- * thumbnails without a per-item resolve round-trip.
- *
- * Picker stays open across selections (so authors can pick several
- * without re-opening) and auto-stops when `max` is reached.
- * Selected items render as a vertical list with up/down reorder
- * and per-item removal; drag-reorder is deferred to a follow-up
- * (see `MediaListPickerField`).
+ * Build a typed `media` reference field — `media("hero")`. The picker
+ * opens the Media Library in modal mode; `.accept()` filters the grid
+ * (and re-validates on write), `.multiple()` stores an id array.
  */
-export function mediaList(options) {
-    const scope = { accept: options.accept };
-    return {
-        key: options.key,
-        label: options.label,
-        type: "json",
-        inputType: "mediaList",
-        referenceTarget: {
-            kind: "media",
-            scope,
-            valueShape: "object",
-            multiple: true,
-        },
-        max: options.max,
-        required: options.required,
-        description: options.description,
-        default: options.default,
-        span: options.span,
-    };
+export function media(key) {
+    return new MediaFieldBuilder(key);
 }
 //# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,KAAK,CAAC,OAA0B;IAC9C,MAAM,KAAK,GAAoB,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC1D,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,MAAM;QACZ,SAAS,EAAE,OAAO;QAClB,eAAe,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC/D,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC;AACJ,CAAC;AAmBD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS,CACvB,OAA8B;IAE9B,MAAM,KAAK,GAAoB,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC1D,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,MAAM;QACZ,SAAS,EAAE,WAAW;QACtB,eAAe,EAAE;YACf,IAAI,EAAE,OAAO;YACb,KAAK;YACL,UAAU,EAAE,QAAQ;YACpB,QAAQ,EAAE,IAAI;SACf;QACD,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/fields.d.ts

@@ -1,3 +1,2 @@
-export { media, mediaList } from "./builder.js";
-export type { MediaFieldOptions, MediaListFieldOptions, MediaValue, } from "./builder.js";
+export { media, MediaFieldBuilder } from "./builder.js";
 //# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,GACX,MAAM,cAAc,CAAC"}
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/fields.js

@@ -3,5 +3,5 @@
 // with `media()` (the plugin descriptor factory) exported from the
 // package root. Mirrors the `plumix/fields` subpath convention from
 // core.
-export { media, mediaList } from "./builder.js";
+export { media, MediaFieldBuilder } from "./builder.js";
 //# sourceMappingURL=fields.js.map

package/dist/fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"fields.js","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,sEAAsE;AACtE,mEAAmE;AACnE,oEAAoE;AACpE,QAAQ;AAER,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,sEAAsE;AACtE,mEAAmE;AACnE,oEAAoE;AACpE,QAAQ;AAER,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { PluginDescriptor } from "plumix/plugin";
 import { DEFAULT_ACCEPTED_TYPES } from "./mime.js";
-export type { MediaFieldScope } from "./lookup.js";
+export type { MediaFieldScope, MediaReference } from "./lookup.js";
 export { DEFAULT_ACCEPTED_TYPES };
 /** Default max upload size — 25 MiB. */
 export declare const DEFAULT_MAX_UPLOAD_SIZE: number;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAKnD,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAgExD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,UAAU,kBAAkB;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,KAAK,CACnB,OAAO,GAAE,kBAAuB,GAC/B,gBAAgB,CAAC,SAAS,CAAC,CA8G7B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAKnD,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC,wCAAwC;AACxC,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAgExD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,UAAU,kBAAkB;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,KAAK,CACnB,OAAO,GAAE,kBAAuB,GAC/B,gBAAgB,CAAC,SAAS,CAAC,CA8G7B"}

package/dist/lookup.d.ts

@@ -1,4 +1,4 @@
-import type { LookupAdapter } from "plumix/plugin";
+import type { HydratedReference, LookupResult } from "plumix/plugin";
 /**
  * Public scope shape for the `media` reference field. Carried on the
  * field's `referenceTarget.scope`; the media `LookupAdapter` consumes
@@ -14,12 +14,32 @@ import type { LookupAdapter } from "plumix/plugin";
 export interface MediaFieldScope {
     readonly accept?: string | readonly string[];
 }
+/**
+ * Hydrated shape of a `media` reference — the read pipeline resolves
+ * stored ids into this at read time, so themes can render a media meta
+ * field (URL included) without a manual fetch. `id` stays the stored
+ * string id so a hydrated value posted back through a meta write
+ * self-heals to the plain id.
+ */
+export interface MediaReference extends HydratedReference {
+    readonly title: string;
+    readonly mime: string;
+    readonly size: number;
+    readonly alt: string | null;
+    readonly url: string;
+    readonly thumbnailUrl: string;
+    readonly width: number | null;
+    readonly height: number | null;
+}
+declare module "plumix/plugin" {
+    interface ReferenceHydrationShapes {
+        readonly media: MediaReference;
+    }
+}
 /**
  * Server-side adapter for the `media` reference field. Storage is the
- * cached-object shape (`{ id, mime, filename }`) — the meta pipeline
- * pulls `cached` from `LookupResult` and merges it into the stored
- * value on every write so reads render thumbnails without an extra
- * resolve round-trip.
+ * plain media id; `hydrate` resolves ids into `MediaReference` (URL
+ * included) at read time through the shared meta pipeline.
  *
  * Queries:
  *  - `list({ ids })`: PK lookup via `inArray(entries.id, …)` + the
@@ -39,5 +59,9 @@ export interface MediaFieldScope {
  * `media.confirm` (flips to published) — referencing one would point
  * at an asset whose bytes haven't been verified.
  */
-export declare const mediaLookupAdapter: LookupAdapter<MediaFieldScope>;
+export declare const mediaLookupAdapter: {
+    list(ctx: import("@plumix/core").AppContext, options: import("@plumix/core").LookupListOptions<MediaFieldScope>): Promise<LookupResult[]>;
+    resolve(ctx: import("@plumix/core").AppContext, id: string, scope?: MediaFieldScope | undefined): Promise<LookupResult | null>;
+    hydrate(ctx: import("@plumix/core").AppContext, options: import("@plumix/core").LookupHydrateOptions<MediaFieldScope>): Promise<MediaReference[]>;
+};
 //# sourceMappingURL=lookup.d.ts.map

package/dist/lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,eAAe,CAAC;AAgBtE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,eAAe,CA4D7D,CAAC"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAEjB,YAAY,EAEb,MAAM,eAAe,CAAC;AAiBvB;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,wBAAwB;QAChC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;KAChC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,eAAO,MAAM,kBAAkB;;;;CA6GW,CAAC"}

package/dist/lookup.js

@@ -1,5 +1,6 @@
 import { and, desc, entries, eq, inArray, like, sql } from "plumix/plugin";
 import { parseMediaMeta } from "./meta.js";
+import { resolveMediaUrl, thumbnailFor } from "./read-service.js";
 const MEDIA_ENTRY_TYPE = "media";
 const DEFAULT_LIST_LIMIT = 24;
 const MAX_LIST_LIMIT = 100;
@@ -10,10 +11,8 @@ const MEDIA_ROW_COLUMNS = {
 };
 /**
  * Server-side adapter for the `media` reference field. Storage is the
- * cached-object shape (`{ id, mime, filename }`) — the meta pipeline
- * pulls `cached` from `LookupResult` and merges it into the stored
- * value on every write so reads render thumbnails without an extra
- * resolve round-trip.
+ * plain media id; `hydrate` resolves ids into `MediaReference` (URL
+ * included) at read time through the shared meta pipeline.
  *
  * Queries:
  *  - `list({ ids })`: PK lookup via `inArray(entries.id, …)` + the
@@ -33,6 +32,8 @@ const MEDIA_ROW_COLUMNS = {
  * `media.confirm` (flips to published) — referencing one would point
  * at an asset whose bytes haven't been verified.
  */
+// `satisfies` keeps `hydrate`'s concrete `MediaReference` return type
+// visible instead of widening to the contract's `HydratedReference`.
 export const mediaLookupAdapter = {
     async list(ctx, options) {
         const conditions = [
@@ -98,6 +99,49 @@ export const mediaLookupAdapter = {
             return null;
         return toLookupResult(row.id, row.title, meta.mime);
     },
+    async hydrate(ctx, options) {
+        const numericIds = options.ids
+            .map((id) => parseMediaId(id))
+            .filter((id) => id !== null);
+        if (numericIds.length === 0)
+            return [];
+        const conditions = [
+            eq(entries.type, MEDIA_ENTRY_TYPE),
+            eq(entries.status, "published"),
+            inArray(entries.id, numericIds),
+        ];
+        const acceptCondition = buildAcceptCondition(options.scope?.accept);
+        if (acceptCondition)
+            conditions.push(acceptCondition);
+        const rows = await ctx.db
+            .select(MEDIA_ROW_COLUMNS)
+            .from(entries)
+            .where(and(...conditions))
+            .limit(numericIds.length);
+        const parsed = rows.flatMap((row) => {
+            const meta = parseMediaMeta(row.meta);
+            return meta ? [{ row, meta }] : [];
+        });
+        // `storage.url()` can be a signing round-trip — resolve the batch
+        // concurrently. Same URL resolution as `buildMediaItem`
+        // (read-service) so a hydrated reference and `media.get` agree.
+        return Promise.all(parsed.map(async ({ row, meta }) => {
+            const url = ctx.storage
+                ? await resolveMediaUrl(ctx.storage, meta.storageKey, row.id, ctx.basePath)
+                : meta.storageKey;
+            return {
+                id: String(row.id),
+                title: row.title,
+                mime: meta.mime,
+                size: meta.size,
+                alt: meta.alt,
+                url,
+                thumbnailUrl: thumbnailFor(ctx, url, meta.mime),
+                width: meta.width,
+                height: meta.height,
+            };
+        }));
+    },
 };
 function parseMediaId(id) {
     if (!/^[1-9]\d{0,15}$/.test(id))
@@ -139,8 +183,7 @@ function buildAcceptCondition(accept) {
 function toLookupResult(id, title, mime) {
     // Mirror the entry adapter's `null` contract for empty/whitespace
     // titles so admin pickers render a localized "Untitled" descriptor
-    // rather than an empty `<p>`. `cached.filename` keeps the raw value
-    // (deletion-resilient consumers may still want the original token).
+    // rather than an empty `<p>`.
     const trimmedTitle = title.trim();
     const label = trimmedTitle !== "" ? trimmedTitle : null;
     return {
@@ -148,7 +191,6 @@ function toLookupResult(id, title, mime) {
         label,
         targetType: MEDIA_ENTRY_TYPE,
         subtitle: mime,
-        cached: { mime, filename: title },
     };
 }
 //# sourceMappingURL=lookup.js.map