@anvilkit/plugin-asset-manager 0.1.8 → 0.1.10

package/dist/types/resumable.d.cts

@@ -0,0 +1,204 @@
+/**
+ * @file Resumable / multipart upload contract (PRD 0004 §5.1 — "High #1").
+ *
+ * A session-based alternative to the single-shot {@link UploadAdapter}. A large
+ * file is split into ordered parts; each part uploads independently and is
+ * retried in isolation, and an interrupted upload can resume from the parts the
+ * backend already accepted (the session store added in M2 persists those
+ * acknowledgements). The final artifact is still a single {@link UploadResult}
+ * that flows through `validateUploadResult()` before registry insertion — the
+ * trust boundary is unchanged.
+ *
+ * Dependency-free by design: the built-in S3 implementation (M4) drives an
+ * extended presign endpoint rather than bundling the AWS SDK, mirroring
+ * `s3PresignedAdapter`. The runner (M3) is adapter-agnostic — it owns slicing,
+ * per-part retry, progress, resume, and abort, and never assumes S3.
+ *
+ * @experimental Public surface may change before v1.0.
+ */
+import type { UploadAdapter, UploadAdapterOptions, UploadResult } from "./types.js";
+/**
+ * One contiguous chunk of the source file handed to
+ * {@link ResumableUploadAdapter.uploadPart}.
+ */
+export interface UploadPart {
+    /**
+     * 1-based part index — contiguous and ascending. S3 multipart numbers parts
+     * from 1, so the runner and adapters share that convention with no offset.
+     */
+    readonly partNumber: number;
+    /** Byte offset of this part within the source file. */
+    readonly start: number;
+    /** Exclusive end offset; `end - start === blob.size`. */
+    readonly end: number;
+    /** The chunk body — a `File.slice(start, end)` of the source. */
+    readonly blob: Blob;
+}
+/**
+ * Opaque acknowledgement of a successfully stored part. `etag` is the value the
+ * backend requires at completion (S3 returns one per `UploadPart`); the runner
+ * persists it so the part is skipped when a session resumes.
+ */
+export interface PartTag {
+    readonly partNumber: number;
+    readonly etag: string;
+}
+/**
+ * Backend handle for an in-progress multipart upload, returned by
+ * {@link ResumableUploadAdapter.begin}.
+ *
+ * `uploadId` is the backend's session id (e.g. S3 `UploadId`). A non-empty
+ * `parts` marks a *resumed* session — the runner skips those part numbers
+ * rather than re-uploading them. `meta` is host-opaque continuation data that
+ * round-trips unchanged back to `uploadPart` / `complete` / `abort`.
+ */
+export interface UploadSession {
+    readonly uploadId: string;
+    /** Parts already accepted by the backend (empty/omitted for a fresh session). */
+    readonly parts?: readonly PartTag[];
+    /**
+     * Effective part size in bytes, **locked for the life of the session**. The
+     * runner slices every part at this size, so resuming MUST reuse the same
+     * value — otherwise a skipped `partNumber` would map to a different byte
+     * range and corrupt the object. A backend may dictate it here; otherwise the
+     * runner sets it from config and persists it (see {@link
+     * PersistedUploadSession.partSize}). Once parts have been uploaded it must
+     * not change.
+     */
+    readonly partSize?: number;
+    /**
+     * Host-opaque continuation data echoed back to subsequent calls. Typed
+     * JSON-safe so the runner can persist it directly into
+     * {@link PersistedUploadSession.meta} (which the M2 session store round-trips
+     * through `localStorage`) without a lossy conversion.
+     */
+    readonly meta?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Any value that survives `JSON.stringify` → `JSON.parse` (and `structuredClone`)
+ * unchanged. Used to type persisted continuation data so the M2 session store
+ * can round-trip it through `localStorage` without silently dropping functions,
+ * symbols, `BigInt`, class instances, or cyclic references.
+ *
+ * NOTE: numbers must be **finite** — `NaN` and `±Infinity` serialize to `null`
+ * via `JSON.stringify`, so they do not round-trip. The session store treats
+ * non-finite numeric meta as a host bug.
+ */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * The serializable subset of an {@link UploadSession} that the M2 session store
+ * persists so an interrupted upload can resume after a reload. The runner loads
+ * it (keyed by file fingerprint) and hands it to
+ * {@link ResumableUploadAdapter.begin} as the `resume` argument. MUST be JSON /
+ * structured-clone safe end-to-end — it round-trips through `localStorage`.
+ */
+export interface PersistedUploadSession {
+    /** Backend session id (e.g. S3 `UploadId`) to reconcile against. */
+    readonly uploadId: string;
+    /** The effective part size locked in when the session started (bytes). */
+    readonly partSize: number;
+    /** Parts the backend had accepted at persist time. */
+    readonly parts: readonly PartTag[];
+    /**
+     * Host-opaque continuation data. Typed as JSON-safe so the persisted handle
+     * is serializable by construction, not just by convention.
+     */
+    readonly meta?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Persistence seam for resumable uploads. The runner loads a prior session
+ * before {@link ResumableUploadAdapter.begin} (so an interrupted upload can
+ * resume), saves progress as parts complete, and clears it once the upload
+ * finishes or is abandoned. Keyed internally by a stable file fingerprint
+ * (name + size + lastModified), so the same picked file resumes while a
+ * different file does not.
+ *
+ * The built-in `createUploadSessionStore` persists to `localStorage` (with an
+ * in-memory fallback where unavailable); hosts may supply their own (e.g.
+ * IndexedDB or remote), hence the optionally-async return types.
+ */
+export interface UploadSessionStore {
+    /** Look up a persisted session for `file`, or `undefined` if none. */
+    load(file: File): PersistedUploadSession | undefined | Promise<PersistedUploadSession | undefined>;
+    /** Persist (or overwrite) the in-progress session for `file`. Best-effort. */
+    save(file: File, session: PersistedUploadSession): void | Promise<void>;
+    /** Remove any persisted session for `file` — called on complete or abort. */
+    clear(file: File): void | Promise<void>;
+}
+/**
+ * Session-based upload backend. Contrast with {@link UploadAdapter}, which is a
+ * single `File → UploadResult` call. Implementations own the four lifecycle
+ * steps; the adapter-agnostic runner (M3) drives them and handles slicing,
+ * per-part retry, progress, resume, and abort.
+ *
+ * Transient failures (HTTP 5xx, network) should be thrown as `RetryableError`
+ * so the runner retries the individual part; non-retryable failures (4xx,
+ * shape errors) should throw `AssetValidationError`, matching the single-shot
+ * adapter convention.
+ */
+export interface ResumableUploadAdapter {
+    /**
+     * Open — or resume — a multipart session for `file`.
+     *
+     * When `resume` is supplied (a persisted handle from a prior, interrupted
+     * run), the adapter SHOULD reconcile against that backend session — e.g. S3
+     * `ListParts` against `resume.uploadId` — and return a session that echoes
+     * the still-valid `uploadId` and accepted `parts` so the runner skips them.
+     * If `resume.uploadId` is reused, the returned session's effective
+     * `partSize` MUST equal `resume.partSize` — the byte ranges of already-
+     * uploaded parts depend on it. If the backend session is gone or expired the
+     * adapter MUST start fresh: return a new `uploadId` with empty `parts`. When
+     * `resume` is omitted this always starts a fresh session.
+     */
+    readonly begin: (file: File, resume?: PersistedUploadSession, options?: UploadAdapterOptions) => Promise<UploadSession>;
+    /** Upload one part and return its completion tag. */
+    readonly uploadPart: (session: UploadSession, part: UploadPart, options?: UploadAdapterOptions) => Promise<PartTag>;
+    /**
+     * Finalize the session once every part is stored. `parts` is the full,
+     * part-number-ordered tag set (resumed + freshly uploaded). Returns the
+     * asset row, which is then validated like any other upload result.
+     */
+    readonly complete: (session: UploadSession, parts: readonly PartTag[], options?: UploadAdapterOptions) => Promise<UploadResult>;
+    /**
+     * Best-effort teardown of an aborted or failed session (e.g. S3
+     * `AbortMultipartUpload`). The runner calls this on abort; implementations
+     * should swallow their own errors so cleanup never masks the original
+     * failure.
+     */
+    readonly abort: (session: UploadSession, options?: UploadAdapterOptions) => Promise<void>;
+}
+/**
+ * Resumable / multipart upload configuration on {@link AssetManagerOptions}.
+ */
+export interface ResumableUploadConfig {
+    /** The multipart backend driving begin / uploadPart / complete / abort. */
+    readonly adapter: ResumableUploadAdapter;
+    /**
+     * Bytes per part. Defaults to 8 MiB in the runner. S3 requires every part
+     * except the last to be ≥ 5 MiB, so the S3 adapter clamps smaller values.
+     */
+    readonly partSize?: number;
+    /**
+     * Minimum file size (bytes) routed through the resumable path; smaller files
+     * use the single-shot `uploader`. Defaults to `partSize` — a file that fits
+     * in one part gains nothing from multipart.
+     */
+    readonly threshold?: number;
+    /**
+     * Where in-progress sessions are persisted so an interrupted upload can
+     * resume. Omitted ⇒ the runner uses the built-in `createUploadSessionStore`
+     * (localStorage, with an in-memory fallback). Supply a custom store
+     * (IndexedDB, remote) to change the backing.
+     */
+    readonly sessionStore?: UploadSessionStore;
+}
+/**
+ * Narrow an upload backend to a {@link ResumableUploadAdapter}. The single-shot
+ * {@link UploadAdapter} is a function; the resumable adapter is an object with
+ * the four lifecycle methods, so a `typeof === "object"` plus method check
+ * distinguishes them unambiguously.
+ */
+export declare function isResumableAdapter(value: UploadAdapter | ResumableUploadAdapter | undefined): value is ResumableUploadAdapter;
+//# sourceMappingURL=resumable.d.cts.map

package/dist/types/resumable.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumable.d.cts","sourceRoot":"","sources":["../../src/types/resumable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACX,aAAa,EACb,oBAAoB,EACpB,YAAY,EACZ,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAClB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,SAAS,EAAE,GACpB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACtC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,IAAI,CACH,IAAI,EAAE,IAAI,GAER,sBAAsB,GACtB,SAAS,GACT,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IAC/C,8EAA8E;IAC9E,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,6EAA6E;IAC7E,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACtC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,CACf,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,sBAAsB,EAC/B,OAAO,CAAC,EAAE,oBAAoB,KAC1B,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,CACpB,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,oBAAoB,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAClB,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,OAAO,CAAC,EAAE,oBAAoB,KAC1B,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,CACf,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,oBAAoB,KAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,aAAa,GAAG,sBAAsB,GAAG,SAAS,GACvD,KAAK,IAAI,sBAAsB,CASjC"}

package/dist/types/resumable.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @file Resumable / multipart upload contract (PRD 0004 §5.1 — "High #1").
+ *
+ * A session-based alternative to the single-shot {@link UploadAdapter}. A large
+ * file is split into ordered parts; each part uploads independently and is
+ * retried in isolation, and an interrupted upload can resume from the parts the
+ * backend already accepted (the session store added in M2 persists those
+ * acknowledgements). The final artifact is still a single {@link UploadResult}
+ * that flows through `validateUploadResult()` before registry insertion — the
+ * trust boundary is unchanged.
+ *
+ * Dependency-free by design: the built-in S3 implementation (M4) drives an
+ * extended presign endpoint rather than bundling the AWS SDK, mirroring
+ * `s3PresignedAdapter`. The runner (M3) is adapter-agnostic — it owns slicing,
+ * per-part retry, progress, resume, and abort, and never assumes S3.
+ *
+ * @experimental Public surface may change before v1.0.
+ */
+import type { UploadAdapter, UploadAdapterOptions, UploadResult } from "./types.js";
+/**
+ * One contiguous chunk of the source file handed to
+ * {@link ResumableUploadAdapter.uploadPart}.
+ */
+export interface UploadPart {
+    /**
+     * 1-based part index — contiguous and ascending. S3 multipart numbers parts
+     * from 1, so the runner and adapters share that convention with no offset.
+     */
+    readonly partNumber: number;
+    /** Byte offset of this part within the source file. */
+    readonly start: number;
+    /** Exclusive end offset; `end - start === blob.size`. */
+    readonly end: number;
+    /** The chunk body — a `File.slice(start, end)` of the source. */
+    readonly blob: Blob;
+}
+/**
+ * Opaque acknowledgement of a successfully stored part. `etag` is the value the
+ * backend requires at completion (S3 returns one per `UploadPart`); the runner
+ * persists it so the part is skipped when a session resumes.
+ */
+export interface PartTag {
+    readonly partNumber: number;
+    readonly etag: string;
+}
+/**
+ * Backend handle for an in-progress multipart upload, returned by
+ * {@link ResumableUploadAdapter.begin}.
+ *
+ * `uploadId` is the backend's session id (e.g. S3 `UploadId`). A non-empty
+ * `parts` marks a *resumed* session — the runner skips those part numbers
+ * rather than re-uploading them. `meta` is host-opaque continuation data that
+ * round-trips unchanged back to `uploadPart` / `complete` / `abort`.
+ */
+export interface UploadSession {
+    readonly uploadId: string;
+    /** Parts already accepted by the backend (empty/omitted for a fresh session). */
+    readonly parts?: readonly PartTag[];
+    /**
+     * Effective part size in bytes, **locked for the life of the session**. The
+     * runner slices every part at this size, so resuming MUST reuse the same
+     * value — otherwise a skipped `partNumber` would map to a different byte
+     * range and corrupt the object. A backend may dictate it here; otherwise the
+     * runner sets it from config and persists it (see {@link
+     * PersistedUploadSession.partSize}). Once parts have been uploaded it must
+     * not change.
+     */
+    readonly partSize?: number;
+    /**
+     * Host-opaque continuation data echoed back to subsequent calls. Typed
+     * JSON-safe so the runner can persist it directly into
+     * {@link PersistedUploadSession.meta} (which the M2 session store round-trips
+     * through `localStorage`) without a lossy conversion.
+     */
+    readonly meta?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Any value that survives `JSON.stringify` → `JSON.parse` (and `structuredClone`)
+ * unchanged. Used to type persisted continuation data so the M2 session store
+ * can round-trip it through `localStorage` without silently dropping functions,
+ * symbols, `BigInt`, class instances, or cyclic references.
+ *
+ * NOTE: numbers must be **finite** — `NaN` and `±Infinity` serialize to `null`
+ * via `JSON.stringify`, so they do not round-trip. The session store treats
+ * non-finite numeric meta as a host bug.
+ */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * The serializable subset of an {@link UploadSession} that the M2 session store
+ * persists so an interrupted upload can resume after a reload. The runner loads
+ * it (keyed by file fingerprint) and hands it to
+ * {@link ResumableUploadAdapter.begin} as the `resume` argument. MUST be JSON /
+ * structured-clone safe end-to-end — it round-trips through `localStorage`.
+ */
+export interface PersistedUploadSession {
+    /** Backend session id (e.g. S3 `UploadId`) to reconcile against. */
+    readonly uploadId: string;
+    /** The effective part size locked in when the session started (bytes). */
+    readonly partSize: number;
+    /** Parts the backend had accepted at persist time. */
+    readonly parts: readonly PartTag[];
+    /**
+     * Host-opaque continuation data. Typed as JSON-safe so the persisted handle
+     * is serializable by construction, not just by convention.
+     */
+    readonly meta?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Persistence seam for resumable uploads. The runner loads a prior session
+ * before {@link ResumableUploadAdapter.begin} (so an interrupted upload can
+ * resume), saves progress as parts complete, and clears it once the upload
+ * finishes or is abandoned. Keyed internally by a stable file fingerprint
+ * (name + size + lastModified), so the same picked file resumes while a
+ * different file does not.
+ *
+ * The built-in `createUploadSessionStore` persists to `localStorage` (with an
+ * in-memory fallback where unavailable); hosts may supply their own (e.g.
+ * IndexedDB or remote), hence the optionally-async return types.
+ */
+export interface UploadSessionStore {
+    /** Look up a persisted session for `file`, or `undefined` if none. */
+    load(file: File): PersistedUploadSession | undefined | Promise<PersistedUploadSession | undefined>;
+    /** Persist (or overwrite) the in-progress session for `file`. Best-effort. */
+    save(file: File, session: PersistedUploadSession): void | Promise<void>;
+    /** Remove any persisted session for `file` — called on complete or abort. */
+    clear(file: File): void | Promise<void>;
+}
+/**
+ * Session-based upload backend. Contrast with {@link UploadAdapter}, which is a
+ * single `File → UploadResult` call. Implementations own the four lifecycle
+ * steps; the adapter-agnostic runner (M3) drives them and handles slicing,
+ * per-part retry, progress, resume, and abort.
+ *
+ * Transient failures (HTTP 5xx, network) should be thrown as `RetryableError`
+ * so the runner retries the individual part; non-retryable failures (4xx,
+ * shape errors) should throw `AssetValidationError`, matching the single-shot
+ * adapter convention.
+ */
+export interface ResumableUploadAdapter {
+    /**
+     * Open — or resume — a multipart session for `file`.
+     *
+     * When `resume` is supplied (a persisted handle from a prior, interrupted
+     * run), the adapter SHOULD reconcile against that backend session — e.g. S3
+     * `ListParts` against `resume.uploadId` — and return a session that echoes
+     * the still-valid `uploadId` and accepted `parts` so the runner skips them.
+     * If `resume.uploadId` is reused, the returned session's effective
+     * `partSize` MUST equal `resume.partSize` — the byte ranges of already-
+     * uploaded parts depend on it. If the backend session is gone or expired the
+     * adapter MUST start fresh: return a new `uploadId` with empty `parts`. When
+     * `resume` is omitted this always starts a fresh session.
+     */
+    readonly begin: (file: File, resume?: PersistedUploadSession, options?: UploadAdapterOptions) => Promise<UploadSession>;
+    /** Upload one part and return its completion tag. */
+    readonly uploadPart: (session: UploadSession, part: UploadPart, options?: UploadAdapterOptions) => Promise<PartTag>;
+    /**
+     * Finalize the session once every part is stored. `parts` is the full,
+     * part-number-ordered tag set (resumed + freshly uploaded). Returns the
+     * asset row, which is then validated like any other upload result.
+     */
+    readonly complete: (session: UploadSession, parts: readonly PartTag[], options?: UploadAdapterOptions) => Promise<UploadResult>;
+    /**
+     * Best-effort teardown of an aborted or failed session (e.g. S3
+     * `AbortMultipartUpload`). The runner calls this on abort; implementations
+     * should swallow their own errors so cleanup never masks the original
+     * failure.
+     */
+    readonly abort: (session: UploadSession, options?: UploadAdapterOptions) => Promise<void>;
+}
+/**
+ * Resumable / multipart upload configuration on {@link AssetManagerOptions}.
+ */
+export interface ResumableUploadConfig {
+    /** The multipart backend driving begin / uploadPart / complete / abort. */
+    readonly adapter: ResumableUploadAdapter;
+    /**
+     * Bytes per part. Defaults to 8 MiB in the runner. S3 requires every part
+     * except the last to be ≥ 5 MiB, so the S3 adapter clamps smaller values.
+     */
+    readonly partSize?: number;
+    /**
+     * Minimum file size (bytes) routed through the resumable path; smaller files
+     * use the single-shot `uploader`. Defaults to `partSize` — a file that fits
+     * in one part gains nothing from multipart.
+     */
+    readonly threshold?: number;
+    /**
+     * Where in-progress sessions are persisted so an interrupted upload can
+     * resume. Omitted ⇒ the runner uses the built-in `createUploadSessionStore`
+     * (localStorage, with an in-memory fallback). Supply a custom store
+     * (IndexedDB, remote) to change the backing.
+     */
+    readonly sessionStore?: UploadSessionStore;
+}
+/**
+ * Narrow an upload backend to a {@link ResumableUploadAdapter}. The single-shot
+ * {@link UploadAdapter} is a function; the resumable adapter is an object with
+ * the four lifecycle methods, so a `typeof === "object"` plus method check
+ * distinguishes them unambiguously.
+ */
+export declare function isResumableAdapter(value: UploadAdapter | ResumableUploadAdapter | undefined): value is ResumableUploadAdapter;
+//# sourceMappingURL=resumable.d.ts.map

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

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

package/dist/types/resumable.js

@@ -0,0 +1,4 @@
+function isResumableAdapter(value) {
+    return "object" == typeof value && null !== value && "function" == typeof value.begin && "function" == typeof value.uploadPart && "function" == typeof value.complete && "function" == typeof value.abort;
+}
+export { isResumableAdapter };

package/dist/types/transform.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/types/transform.d.cts

@@ -0,0 +1,45 @@
+/**
+ * @file Asset transformation contract (PRD 0004 — review finding #9).
+ *
+ * A headless, processing-free transformation seam. The plugin never resizes or
+ * transcodes bytes itself (it has no storage either — uploads go through host
+ * adapters); instead a transform is a declarative spec carried alongside an
+ * `asset://<id>` reference, and a host-pluggable {@link TransformResolver} maps
+ * `(asset, transform)` to a derivative URL produced by the host's image CDN /
+ * service (imgix, Cloudinary, S3 + Lambda, …). The built-in
+ * `createQueryParamTransformResolver` covers the common query-param CDN case.
+ *
+ * @experimental Public surface may change before v1.0.
+ */
+import type { UploadResult } from "./types.js";
+/**
+ * A declarative, backend-neutral image transformation request. All fields are
+ * optional; a resolver maps the ones it supports onto its CDN's vocabulary and
+ * ignores the rest.
+ */
+export interface AssetTransform {
+    /** Target width in pixels. */
+    readonly width?: number;
+    /** Target height in pixels. */
+    readonly height?: number;
+    /**
+     * How the image fills the target box when both `width` and `height` are set.
+     * Names follow the common CDN/sharp vocabulary; a resolver maps them onto its
+     * own parameter values.
+     */
+    readonly fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+    /** Output format. `"auto"` lets the CDN negotiate (e.g. WebP/AVIF by Accept). */
+    readonly format?: "webp" | "avif" | "jpeg" | "png" | "auto";
+    /** Output quality, 1–100. */
+    readonly quality?: number;
+    /** Device pixel ratio multiplier (e.g. `2` for retina). */
+    readonly dpr?: number;
+}
+/**
+ * Host-pluggable mapping from an asset + transform spec to a derivative URL.
+ * Return `undefined` to fall back to the asset's original URL (e.g. the
+ * transform isn't supported, or the asset isn't an image). The returned URL is
+ * re-validated through the same trust boundary as any other resolved asset URL.
+ */
+export type TransformResolver = (asset: UploadResult, transform: AssetTransform) => string | undefined;
+//# sourceMappingURL=transform.d.cts.map

package/dist/types/transform.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.cts","sourceRoot":"","sources":["../../src/types/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACnE,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5D,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC/B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,CAAC"}

package/dist/types/transform.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Asset transformation contract (PRD 0004 — review finding #9).
+ *
+ * A headless, processing-free transformation seam. The plugin never resizes or
+ * transcodes bytes itself (it has no storage either — uploads go through host
+ * adapters); instead a transform is a declarative spec carried alongside an
+ * `asset://<id>` reference, and a host-pluggable {@link TransformResolver} maps
+ * `(asset, transform)` to a derivative URL produced by the host's image CDN /
+ * service (imgix, Cloudinary, S3 + Lambda, …). The built-in
+ * `createQueryParamTransformResolver` covers the common query-param CDN case.
+ *
+ * @experimental Public surface may change before v1.0.
+ */
+import type { UploadResult } from "./types.js";
+/**
+ * A declarative, backend-neutral image transformation request. All fields are
+ * optional; a resolver maps the ones it supports onto its CDN's vocabulary and
+ * ignores the rest.
+ */
+export interface AssetTransform {
+    /** Target width in pixels. */
+    readonly width?: number;
+    /** Target height in pixels. */
+    readonly height?: number;
+    /**
+     * How the image fills the target box when both `width` and `height` are set.
+     * Names follow the common CDN/sharp vocabulary; a resolver maps them onto its
+     * own parameter values.
+     */
+    readonly fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+    /** Output format. `"auto"` lets the CDN negotiate (e.g. WebP/AVIF by Accept). */
+    readonly format?: "webp" | "avif" | "jpeg" | "png" | "auto";
+    /** Output quality, 1–100. */
+    readonly quality?: number;
+    /** Device pixel ratio multiplier (e.g. `2` for retina). */
+    readonly dpr?: number;
+}
+/**
+ * Host-pluggable mapping from an asset + transform spec to a derivative URL.
+ * Return `undefined` to fall back to the asset's original URL (e.g. the
+ * transform isn't supported, or the asset isn't an image). The returned URL is
+ * re-validated through the same trust boundary as any other resolved asset URL.
+ */
+export type TransformResolver = (asset: UploadResult, transform: AssetTransform) => string | undefined;
+//# sourceMappingURL=transform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/types/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACnE,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5D,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC/B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,CAAC"}

package/dist/types/transform.js

@@ -0,0 +1 @@
+export { };

package/dist/types/types.d.cts

@@ -1,8 +1,16 @@
+/** Optional metadata associated with an uploaded asset. */
 export interface AssetMeta {
     readonly size?: number;
     readonly mimeType?: string;
     readonly width?: number;
     readonly height?: number;
+    /**
+     * Lowercase-hex content digest (SHA-256) of the uploaded bytes. Populated by
+     * the plugin when `dedupe` is enabled — used to detect duplicate uploads and
+     * as an integrity/cacheability signal. A host uploader may also set it
+     * directly; it is preserved through the validate/freeze reconstruction.
+     */
+    readonly hash?: string;
     /**
      * Optional provenance/attribution for externally-sourced assets (PRD 0002
      * §8.4). Set when an asset is inserted from a credit-requiring provider such
@@ -32,6 +40,7 @@ export interface AssetMeta {
  * the headless registry and the Studio surface without translation.
  */
 export type AssetKind = "image" | "video" | "audio" | "font" | "document" | "other";
+/** Normalized asset row returned by upload adapters and registry mutations. */
 export interface UploadResult {
     readonly url: string;
     readonly id: string;
@@ -61,6 +70,13 @@ export interface UploadAdapterOptions {
     readonly signal?: AbortSignal;
 }
 export type UploadAdapter = (file: File, options?: UploadAdapterOptions) => Promise<UploadResult>;
+/**
+ * Lifecycle hook fired when an asset is deleted through the asset source, with
+ * the record as it existed at deletion time. Lets a host release backend
+ * objects tied to the upload (e.g. delete the stored S3 object, revoke a
+ * `blob:` URL). Awaited; throwing rejects the delete.
+ */
+export type AssetDeletedHook = (asset: UploadResult) => void | Promise<void>;
 /**
  * Listener invoked after every registry mutation
  * (`register` / `delete` / `rename` / `replace` / `setTags`). The
@@ -96,6 +112,7 @@ export interface AssetSearchPage {
     readonly total: number;
     readonly nextCursor: string | undefined;
 }
+/** In-memory catalog API that stores and searches uploaded assets. */
 export interface AssetRegistry {
     readonly register: (asset: UploadResult) => UploadResult;
     readonly get: (id: string) => UploadResult | undefined;

package/dist/types/types.d.cts.map

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

package/dist/types/types.d.ts

@@ -1,8 +1,16 @@
+/** Optional metadata associated with an uploaded asset. */
 export interface AssetMeta {
     readonly size?: number;
     readonly mimeType?: string;
     readonly width?: number;
     readonly height?: number;
+    /**
+     * Lowercase-hex content digest (SHA-256) of the uploaded bytes. Populated by
+     * the plugin when `dedupe` is enabled — used to detect duplicate uploads and
+     * as an integrity/cacheability signal. A host uploader may also set it
+     * directly; it is preserved through the validate/freeze reconstruction.
+     */
+    readonly hash?: string;
     /**
      * Optional provenance/attribution for externally-sourced assets (PRD 0002
      * §8.4). Set when an asset is inserted from a credit-requiring provider such
@@ -32,6 +40,7 @@ export interface AssetMeta {
  * the headless registry and the Studio surface without translation.
  */
 export type AssetKind = "image" | "video" | "audio" | "font" | "document" | "other";
+/** Normalized asset row returned by upload adapters and registry mutations. */
 export interface UploadResult {
     readonly url: string;
     readonly id: string;
@@ -61,6 +70,13 @@ export interface UploadAdapterOptions {
     readonly signal?: AbortSignal;
 }
 export type UploadAdapter = (file: File, options?: UploadAdapterOptions) => Promise<UploadResult>;
+/**
+ * Lifecycle hook fired when an asset is deleted through the asset source, with
+ * the record as it existed at deletion time. Lets a host release backend
+ * objects tied to the upload (e.g. delete the stored S3 object, revoke a
+ * `blob:` URL). Awaited; throwing rejects the delete.
+ */
+export type AssetDeletedHook = (asset: UploadResult) => void | Promise<void>;
 /**
  * Listener invoked after every registry mutation
  * (`register` / `delete` / `rename` / `replace` / `setTags`). The
@@ -96,6 +112,7 @@ export interface AssetSearchPage {
     readonly total: number;
     readonly nextCursor: string | undefined;
 }
+/** In-memory catalog API that stores and searches uploaded assets. */
 export interface AssetRegistry {
     readonly register: (asset: UploadResult) => UploadResult;
     readonly get: (id: string) => UploadResult | undefined;