lemon-model 1.2.4 → 1.5.0

package/dist/esm/upload/engine/engine.js

@@ -0,0 +1,204 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { UPLOAD_FAILURE_CODE, UPLOAD_FAILURE_SOURCE } from '../types.js';
+import { UploadProgressTracker } from './progress.js';
+/**
+ * transfers in flight at once.
+ * - a browser queues beyond ~6 per origin, and a queued presigned url burns its `expiresAt` while it waits.
+ * - override per engine when a shell measures something better.
+ */
+export const UPLOAD_DEFAULT_CONCURRENCY = 3;
+/** run `task` over 0..count-1 with at most `limit` in flight; results keep input order */
+const runPooled = (count, limit, task) => __awaiter(void 0, void 0, void 0, function* () {
+    const results = new Array(count);
+    let next = 0;
+    const worker = () => __awaiter(void 0, void 0, void 0, function* () {
+        for (;;) {
+            const index = next++;
+            if (index >= count)
+                return;
+            results[index] = yield task(index);
+        }
+    });
+    const size = Math.max(1, Math.min(limit, count));
+    yield Promise.all(new Array(size).fill(0).map(() => worker()));
+    return results;
+});
+const asContent = (source) => __awaiter(void 0, void 0, void 0, function* () {
+    return ({
+        contentType: source.contentType,
+        contentSize: source.contentSize,
+        width: source.width,
+        height: source.height,
+        hash: source.hash ? yield source.hash() : undefined,
+    });
+});
+const asIntent = (source) => __awaiter(void 0, void 0, void 0, function* () {
+    return (Object.assign(Object.assign({}, (yield asContent(source))), { name: source.name, thumbnail: source.thumbnail ? yield asContent(source.thumbnail) : undefined }));
+});
+/** bytes this source puts on the wire in total; the thumbnail rides along so the bar counts it */
+const sizeOf = (source) => { var _a, _b; return source.contentSize + ((_b = (_a = source.thumbnail) === null || _a === void 0 ? void 0 : _a.contentSize) !== null && _b !== void 0 ? _b : 0); };
+export class UploadEngine {
+    constructor(service, executors, options) {
+        this.service = service;
+        this.executors = executors;
+        this.options = options;
+        this.kinds = executors.map(executor => executor.kind);
+    }
+    /** returns one view per source, in order: `stored`, or `failed` with the reason. `onProgress` gets a snapshot per change */
+    upload(sources, onProgress) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const tracker = new UploadProgressTracker(sources.map(sizeOf), onProgress);
+            tracker.publish();
+            const list = yield Promise.all(sources.map(asIntent));
+            const { list: tickets } = yield this.service.start({ list, transfers: this.kinds });
+            const limit = (_b = (_a = this.options) === null || _a === void 0 ? void 0 : _a.concurrency) !== null && _b !== void 0 ? _b : UPLOAD_DEFAULT_CONCURRENCY;
+            const receipts = yield runPooled(tickets.length, limit, i => this.transferTracked(tickets[i], sources[i], tracker, i));
+            // a server that broke rule 1 (shorter list) must not leave the bar hanging
+            sources.forEach((_, i) => tracker.settle(i));
+            const pending = receipts.filter((item) => !!item);
+            const settled = pending.length ? (yield this.service.complete({ list: pending })).list : [];
+            const byId = new Map(settled.filter(upload => !!upload.id).map((upload) => [upload.id, upload]));
+            return tickets.map(ticket => (ticket.upload.id && byId.get(ticket.upload.id)) || ticket.upload);
+        });
+    }
+    transferTracked(ticket, source, tracker, index) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield this.transfer(ticket, source, tracker.sink(index));
+            }
+            catch (error) {
+                // an executor that throws (a CORS preflight failure surfaces as one) must not take the batch down
+                const id = ticket.upload.id;
+                if (!id)
+                    return undefined;
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    id,
+                    failure: { source: UPLOAD_FAILURE_SOURCE.client, code: UPLOAD_FAILURE_CODE.unknown, message },
+                };
+            }
+            finally {
+                tracker.settle(index);
+            }
+        });
+    }
+    transfer(ticket, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const id = ticket.upload.id;
+            // rejected at start: nothing was created, nothing to complete
+            if (!id)
+                return undefined;
+            const receipt = yield this.transferOriginal(id, ticket.transfer, source, onProgress);
+            // a failed original has nothing to preview; otherwise the thumbnail rides after it (never with it)
+            if (!receipt.failure)
+                yield this.transferThumbnail(id, ticket.thumbnailTransfer, source, onProgress);
+            return receipt;
+        });
+    }
+    transferOriginal(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // no instruction: already stored (dedup, or a stored upload taking only a thumbnail) — complete still confirms it
+            if (!transfer)
+                return { id };
+            const executor = this.executors.find(candidate => candidate.kind === transfer.kind);
+            if (!executor)
+                return { id, failure: { source: UPLOAD_FAILURE_SOURCE.client, code: UPLOAD_FAILURE_CODE.notAcceptable } };
+            // NOTE: `transfer` must not be logged or stored — it may carry a credential url
+            return executor.run(id, transfer, source, onProgress);
+        });
+    }
+    /**
+     * the preview is subordinate: whatever happens here never reaches `complete`.
+     * - `UploadCompleteItem` is one per upload, so reporting a thumbnail failure would fail the original.
+     * - the server settles the thumbnail by looking at storage at `complete` time, so silence is enough.
+     */
+    transferThumbnail(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const thumbnail = source.thumbnail;
+            if (!transfer || !thumbnail)
+                return;
+            const executor = this.executors.find(candidate => candidate.kind === transfer.kind);
+            if (!executor)
+                return;
+            // the original's bytes are already counted, so the thumbnail reports on top of them
+            const base = source.contentSize;
+            try {
+                yield executor.run(id, transfer, thumbnail, sent => onProgress(base + sent));
+            }
+            catch (_a) {
+                // swallowed on purpose: see the note above
+            }
+        });
+    }
+}
+/** lemon-core error convention: "<status> <LABEL> - <detail>" (status 0 = no response, XHR convention) */
+const API_ERROR = /^(\d{1,3}) ([A-Z][A-Z ]*?) - ([\s\S]*)$/;
+const codeOfApiStatus = (status) => {
+    switch (status) {
+        case 0:
+            return UPLOAD_FAILURE_CODE.network;
+        case 400:
+            return UPLOAD_FAILURE_CODE.invalid;
+        case 404:
+            return UPLOAD_FAILURE_CODE.notFound;
+        case 406:
+            return UPLOAD_FAILURE_CODE.notAcceptable;
+        case 409:
+            return UPLOAD_FAILURE_CODE.conflict;
+        case 410:
+            return UPLOAD_FAILURE_CODE.expired;
+        case 413:
+            return UPLOAD_FAILURE_CODE.tooLarge;
+        case 415:
+            return UPLOAD_FAILURE_CODE.unsupported;
+        default:
+            return UPLOAD_FAILURE_CODE.unknown;
+    }
+};
+/** normalize an error thrown by the API adapter */
+export const asApiFailure = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const match = API_ERROR.exec(message);
+    if (!match)
+        return { source: UPLOAD_FAILURE_SOURCE.api, code: UPLOAD_FAILURE_CODE.unknown, message };
+    const status = Number(match[1]);
+    return {
+        source: UPLOAD_FAILURE_SOURCE.api,
+        code: codeOfApiStatus(status),
+        status,
+        reason: match[2],
+        message: match[3],
+    };
+};
+/** S3 error `<Code>` -> normalized code. unknown codes fall back by status */
+const STORAGE_CODES = {
+    SignatureDoesNotMatch: UPLOAD_FAILURE_CODE.signature,
+    AccessDenied: UPLOAD_FAILURE_CODE.expired,
+    ExpiredToken: UPLOAD_FAILURE_CODE.expired,
+    BadDigest: UPLOAD_FAILURE_CODE.checksum,
+    XAmzContentSHA256Mismatch: UPLOAD_FAILURE_CODE.checksum,
+    EntityTooLarge: UPLOAD_FAILURE_CODE.tooLarge,
+    RequestTimeout: UPLOAD_FAILURE_CODE.network,
+};
+/** normalize a non-2xx answer from the storage endpoint (status 0 = no response) */
+export const asStorageFailure = (status, code) => {
+    const known = code ? STORAGE_CODES[code] : undefined;
+    const byStatus = status === 0
+        ? UPLOAD_FAILURE_CODE.network
+        : status === 403
+            ? UPLOAD_FAILURE_CODE.signature
+            : status === 413
+                ? UPLOAD_FAILURE_CODE.tooLarge
+                : UPLOAD_FAILURE_CODE.unknown;
+    return { source: UPLOAD_FAILURE_SOURCE.storage, code: known !== null && known !== void 0 ? known : byStatus, status, reason: code };
+};
+//# sourceMappingURL=engine.js.map

package/dist/esm/upload/engine/engine.js.map

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

package/dist/esm/upload/engine/executors.js

@@ -0,0 +1,57 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { UPLOAD_FAILURE_CODE, UPLOAD_FAILURE_SOURCE, UPLOAD_TRANSFER_KIND } from '../types.js';
+import { asApiFailure, asStorageFailure } from './engine.js';
+import { asContentBytes } from './progress.js';
+/** inline transfer — the only place that knows bytes go to the API as base64 */
+export class InlineExecutor {
+    constructor(send, 
+    /** shell-specific base64 encoder (btoa / Buffer / RN polyfill) */
+    toBase64) {
+        this.send = send;
+        this.toBase64 = toBase64;
+        this.kind = UPLOAD_TRANSFER_KIND.inline;
+    }
+    run(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (source.contentSize > transfer.maxBytes) {
+                return { id, failure: { source: UPLOAD_FAILURE_SOURCE.client, code: UPLOAD_FAILURE_CODE.tooLarge } };
+            }
+            try {
+                const body = { content: this.toBase64(yield source.bytes()) };
+                // wire bytes are base64 JSON (~4/3 of the send): report in send bytes
+                yield this.send(id, body, (loaded, total) => onProgress(asContentBytes(loaded, total, source.contentSize)));
+                return { id };
+            }
+            catch (error) {
+                return { id, failure: asApiFailure(error) };
+            }
+        });
+    }
+}
+/** presigned PUT transfer — raw bytes straight to storage */
+export class PresignedPutExecutor {
+    constructor(put) {
+        this.put = put;
+        this.kind = UPLOAD_TRANSFER_KIND.presignedPut;
+    }
+    run(id, transfer, source, onProgress) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.put(transfer.url, transfer.headers, yield source.bytes(), (loaded, total) => onProgress(asContentBytes(loaded, total, source.contentSize)));
+            if (res.status >= 200 && res.status < 300)
+                return { id };
+            // 412 = object already exists under this key; the server decides at complete
+            if (res.status === 412)
+                return { id };
+            return { id, failure: asStorageFailure(res.status, res.code) };
+        });
+    }
+}
+//# sourceMappingURL=executors.js.map

package/dist/esm/upload/engine/executors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executors.js","sourceRoot":"","sources":["../../../../src/upload/engine/executors.ts"],"names":[],"mappings":";;;;;;;;;AAgBA,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAE5F,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAS5C,gFAAgF;AAChF,MAAM,OAAO,cAAc;IAGvB,YACqB,IAAoB;IACrC,kEAAkE;IACjD,QAAuC;QAFvC,SAAI,GAAJ,IAAI,CAAgB;QAEpB,aAAQ,GAAR,QAAQ,CAA+B;QAL5C,SAAI,GAAG,oBAAoB,CAAC,MAAM,CAAC;IAMhD,CAAC;IAES,GAAG,CACZ,EAAU,EACV,QAA8B,EAC9B,MAA2B,EAC3B,UAA8B;;YAE9B,IAAI,MAAM,CAAC,WAAW,GAAG,QAAQ,CAAC,QAAQ,EAAE;gBACxC,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,qBAAqB,CAAC,MAAM,EAAE,IAAI,EAAE,mBAAmB,CAAC,QAAQ,EAAE,EAAE,CAAC;aACxG;YACD,IAAI;gBACA,MAAM,IAAI,GAAsB,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;gBACjF,sEAAsE;gBACtE,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;gBAC5G,OAAO,EAAE,EAAE,EAAE,CAAC;aACjB;YAAC,OAAO,KAAK,EAAE;gBACZ,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;aAC/C;QACL,CAAC;KAAA;CACJ;AAaD,6DAA6D;AAC7D,MAAM,OAAO,oBAAoB;IAG7B,YAAoC,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;QAF/B,SAAI,GAAG,oBAAoB,CAAC,YAAY,CAAC;IAEP,CAAC;IAEtC,GAAG,CACZ,EAAU,EACV,QAAoC,EACpC,MAA2B,EAC3B,UAA8B;;YAE9B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAC/F,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAChE,CAAC;YACF,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG;gBAAE,OAAO,EAAE,EAAE,EAAE,CAAC;YACzD,6EAA6E;YAC7E,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,EAAE,EAAE,EAAE,CAAC;YACtC,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACnE,CAAC;KAAA;CACJ"}

package/dist/esm/upload/engine/index.js

@@ -0,0 +1,13 @@
+/**
+ * `upload/engine/index.ts`
+ * - isolated entry for the client upload engine: `import { ... } from 'lemon-model/upload/engine'`.
+ * - kept OUT of both the package root barrel and `lemon-model/upload`: a server consumer needs the
+ *   contract only, and must not pull the engine in with it.
+ * - shell adapters (XHR, RN bridge, Electron fs) are NOT here — they belong to the consuming app.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './progress.js';
+export * from './engine.js';
+export * from './executors.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/upload/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/upload/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/dist/esm/upload/engine/progress.js

@@ -0,0 +1,52 @@
+/**
+ * `upload/engine/progress.ts`
+ * - progress is a CLIENT-LOCAL signal: nothing here travels on the wire and no server ever sees it.
+ *   the server's knowledge of progress differs per transfer kind (a presigned PUT it cannot see at all),
+ *   so the contract deliberately carries none of it.
+ * - per-file percent + one batch percent. everything is measured in bytes of the ORIGINAL
+ *   content, never in wire bytes, so the bar means the same thing whichever executor runs.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+/** scale request-body progress (base64 JSON or raw bytes) to original-send bytes */
+export const asContentBytes = (loaded, total, contentSize) => total > 0 ? Math.min(contentSize, Math.round((loaded / total) * contentSize)) : 0;
+/** byte-weighted aggregation; one immutable snapshot per change so a UI store can replace state as-is */
+export class UploadProgressTracker {
+    constructor(totals, emit) {
+        this.emit = emit;
+        this.files = totals.map((total, index) => ({ index, total: Math.max(0, total), settled: false }));
+        this.totalBytes = this.files.reduce((sum, file) => sum + file.total, 0);
+    }
+    /** the per-file sink handed to an executor: clamps to [previous, total], ignores reports after settle */
+    sink(index) {
+        return sent => {
+            var _a;
+            const file = this.files[index];
+            if (!file || file.settled)
+                return;
+            const next = Math.min(file.total, Math.max(sent, (_a = file.sent) !== null && _a !== void 0 ? _a : 0));
+            if (next === file.sent)
+                return;
+            this.files = this.files.map(item => (item.index === index ? Object.assign(Object.assign({}, item), { sent: next }) : item));
+            this.publish();
+        };
+    }
+    settle(index) {
+        const file = this.files[index];
+        if (!file || file.settled)
+            return;
+        this.files = this.files.map(item => (item.index === index ? Object.assign(Object.assign({}, item), { settled: true }) : item));
+        this.publish();
+    }
+    snapshot() {
+        const sentBytes = this.files.reduce((sum, file) => { var _a; return sum + (file.settled ? file.total : (_a = file.sent) !== null && _a !== void 0 ? _a : 0); }, 0);
+        const settled = this.files.filter(file => file.settled).length;
+        const ratio = this.totalBytes > 0 ? sentBytes / this.totalBytes : this.files.length > 0 ? settled / this.files.length : 1;
+        return { files: this.files, totalBytes: this.totalBytes, sentBytes, ratio };
+    }
+    publish() {
+        if (this.emit)
+            this.emit(this.snapshot());
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/esm/upload/engine/progress.js.map

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

package/dist/esm/upload/index.js

@@ -0,0 +1,11 @@
+/**
+ * `upload/index.ts`
+ * - isolated entry for the upload contract: `import { ... } from 'lemon-model/upload'`.
+ * - kept OUT of the package root barrel: a consumer that only needs this contract must not pull
+ *   the socket/genai runtime, and a subpath can be promoted to the root later without a breaking
+ *   change (the reverse is not true).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/upload/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/upload/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,SAAS,CAAC"}

package/dist/esm/upload/testing.js

@@ -0,0 +1,80 @@
+import { UPLOAD_STATUS, UPLOAD_STEREO, UPLOAD_TRANSFER_KIND } from './types.js';
+/** a settled image as the server returns it after `complete`, with the preview the client sent */
+export const SAMPLE_UPLOAD_STORED = {
+    id: 'up-001',
+    status: UPLOAD_STATUS.stored,
+    stereo: UPLOAD_STEREO.image,
+    name: 'photo.png',
+    contentType: 'image/png',
+    contentSize: 123456,
+    url: 'https://cdn.example.com/up-001.png',
+    width: 1024,
+    height: 768,
+    thumbnail: { url: 'https://cdn.example.com/up-001-thumb.jpg', contentType: 'image/jpeg' },
+};
+/** start slot: inline ticket */
+export const SAMPLE_UPLOAD_TICKET_INLINE = {
+    upload: {
+        id: 'up-002',
+        status: UPLOAD_STATUS.pending,
+        stereo: UPLOAD_STEREO.image,
+        name: 'photo.png',
+        contentType: 'image/png',
+        contentSize: 123456,
+    },
+    transfer: { kind: UPLOAD_TRANSFER_KIND.inline, maxBytes: 4000000 },
+};
+/** start slot: presigned PUT ticket */
+export const SAMPLE_UPLOAD_TICKET_PRESIGNED = {
+    upload: {
+        id: 'up-003',
+        status: UPLOAD_STATUS.pending,
+        stereo: UPLOAD_STEREO.image,
+        name: 'photo.png',
+        contentType: 'image/png',
+        contentSize: 123456,
+    },
+    transfer: {
+        kind: UPLOAD_TRANSFER_KIND.presignedPut,
+        method: 'PUT',
+        url: 'https://storage.example.com/up-003?X-Amz-Signature=masked',
+        headers: { 'content-type': 'image/png', 'content-length': '123456' },
+        maxBytes: 50000000,
+        expiresAt: 1757895300000,
+    },
+};
+/**
+ * start slot for an upload that is already `stored` and is only taking a thumbnail.
+ * - `transfer` absent + `thumbnailTransfer` present: the original's bytes are immutable.
+ * - an engine that returns early on a missing `transfer` silently drops the preview.
+ */
+export const SAMPLE_UPLOAD_TICKET_THUMBNAIL_ONLY = {
+    upload: {
+        id: 'up-001',
+        status: UPLOAD_STATUS.stored,
+        stereo: UPLOAD_STEREO.image,
+        name: 'photo.png',
+        contentType: 'image/png',
+        contentSize: 123456,
+        url: 'https://cdn.example.com/up-001.png',
+    },
+    thumbnailTransfer: {
+        kind: UPLOAD_TRANSFER_KIND.presignedPut,
+        method: 'PUT',
+        url: 'https://storage.example.com/up-001-thumb?X-Amz-Signature=masked',
+        headers: { 'content-type': 'image/jpeg' },
+        maxBytes: 200000,
+        expiresAt: 1757895300000,
+    },
+};
+/** start slot rejected at validation: no id, nothing to transfer or complete */
+export const SAMPLE_UPLOAD_REJECTED = {
+    upload: {
+        status: UPLOAD_STATUS.failed,
+        name: 'big.png',
+        contentType: 'image/png',
+        contentSize: 6291456,
+        error: '413 TOO LARGE - 6291456 > 4000000',
+    },
+};
+//# sourceMappingURL=testing.js.map

package/dist/esm/upload/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../../src/upload/testing.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAE7E,kGAAkG;AAClG,MAAM,CAAC,MAAM,oBAAoB,GAAW;IACxC,EAAE,EAAE,QAAQ;IACZ,MAAM,EAAE,aAAa,CAAC,MAAM;IAC5B,MAAM,EAAE,aAAa,CAAC,KAAK;IAC3B,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,WAAW;IACxB,WAAW,EAAE,MAAM;IACnB,GAAG,EAAE,oCAAoC;IACzC,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,GAAG;IACX,SAAS,EAAE,EAAE,GAAG,EAAE,0CAA0C,EAAE,WAAW,EAAE,YAAY,EAAE;CAC5F,CAAC;AAEF,gCAAgC;AAChC,MAAM,CAAC,MAAM,2BAA2B,GAAiB;IACrD,MAAM,EAAE;QACJ,EAAE,EAAE,QAAQ;QACZ,MAAM,EAAE,aAAa,CAAC,OAAO;QAC7B,MAAM,EAAE,aAAa,CAAC,KAAK;QAC3B,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE,MAAM;KACtB;IACD,QAAQ,EAAE,EAAE,IAAI,EAAE,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE;CACrE,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,8BAA8B,GAAiB;IACxD,MAAM,EAAE;QACJ,EAAE,EAAE,QAAQ;QACZ,MAAM,EAAE,aAAa,CAAC,OAAO;QAC7B,MAAM,EAAE,aAAa,CAAC,KAAK;QAC3B,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE,MAAM;KACtB;IACD,QAAQ,EAAE;QACN,IAAI,EAAE,oBAAoB,CAAC,YAAY;QACvC,MAAM,EAAE,KAAK;QACb,GAAG,EAAE,2DAA2D;QAChE,OAAO,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE;QACpE,QAAQ,EAAE,QAAQ;QAClB,SAAS,EAAE,aAAa;KAC3B;CACJ,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAiB;IAC7D,MAAM,EAAE;QACJ,EAAE,EAAE,QAAQ;QACZ,MAAM,EAAE,aAAa,CAAC,MAAM;QAC5B,MAAM,EAAE,aAAa,CAAC,KAAK;QAC3B,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE,MAAM;QACnB,GAAG,EAAE,oCAAoC;KAC5C;IACD,iBAAiB,EAAE;QACf,IAAI,EAAE,oBAAoB,CAAC,YAAY;QACvC,MAAM,EAAE,KAAK;QACb,GAAG,EAAE,iEAAiE;QACtE,OAAO,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE;QACzC,QAAQ,EAAE,MAAM;QAChB,SAAS,EAAE,aAAa;KAC3B;CACJ,CAAC;AAEF,gFAAgF;AAChF,MAAM,CAAC,MAAM,sBAAsB,GAAiB;IAChD,MAAM,EAAE;QACJ,MAAM,EAAE,aAAa,CAAC,MAAM;QAC5B,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,WAAW;QACxB,WAAW,EAAE,OAAO;QACpB,KAAK,EAAE,mCAAmC;KAC7C;CACJ,CAAC"}

package/dist/esm/upload/types.js

@@ -0,0 +1,84 @@
+/**
+ * `upload/types.ts`
+ * - client <-> server contract for uploading files.
+ * - transport-neutral: the client always runs `start` -> transfer -> `complete`; whether the server
+ *   stores bytes inline (base64 in JSON) or hands out a presigned PUT only changes which
+ *   `UploadTransfer` variant it issues.
+ * - runtime-neutral like `socket/`: no Node, DOM, or AWS SDK types. Storage coordinates
+ *   (bucket, key, region) never appear here.
+ * - model-neutral: nothing here imports or names lemon-core's Model/View/Body/Head layers or the `$`
+ *   embed marker. two shapes carry the vocabulary instead — `UploadContent` (bytes as declared) and
+ *   `UploadResource` (bytes as stored, with an address). how a server maps them onto its own model
+ *   layer, and how it embeds an upload in another record, is the server's concern.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+/** kind of stored content */
+export const UPLOAD_STEREO = {
+    image: 'image',
+    video: 'video',
+    sound: 'sound',
+    docs: 'docs',
+};
+/** lifecycle of one upload as the client sees it. `url` is meaningful only when `stored` */
+export const UPLOAD_STATUS = {
+    /** ticket issued; bytes not confirmed by the server yet */
+    pending: 'pending',
+    /** bytes durable and `url` valid */
+    stored: 'stored',
+    /** terminal; `error` carries the server's detail */
+    failed: 'failed',
+};
+/** how bytes travel. a new transfer method arrives as a new kind; the flow around it does not change */
+export const UPLOAD_TRANSFER_KIND = {
+    /** base64 in a JSON body, through the `send` operation */
+    inline: 'inline',
+    /** HTTP PUT straight to storage, to a server-issued url with its headers */
+    presignedPut: 'presigned-put',
+};
+export const isUploadStored = (upload) => upload.status === UPLOAD_STATUS.stored && typeof upload.id === 'string' && typeof upload.url === 'string';
+/** who produced a failure */
+export const UPLOAD_FAILURE_SOURCE = {
+    /** the upload API answered with an error */
+    api: 'api',
+    /** the storage endpoint (presigned PUT) answered with an error */
+    storage: 'storage',
+    /** the client gave up before or without a response */
+    client: 'client',
+};
+/** normalized failure codes; the app branches on these, never on raw HTTP status */
+export const UPLOAD_FAILURE_CODE = {
+    invalid: 'invalid',
+    tooLarge: 'too-large',
+    unsupported: 'unsupported',
+    notAcceptable: 'not-acceptable',
+    notFound: 'not-found',
+    conflict: 'conflict',
+    expired: 'expired',
+    signature: 'signature',
+    checksum: 'checksum',
+    network: 'network',
+    aborted: 'aborted',
+    unknown: 'unknown',
+};
+/** HTTP binding relative to the server's upload base path (lemon-core `/{type}/{id}/{cmd}` shape) */
+export const UPLOAD_ROUTES = {
+    start: { method: 'POST', path: '/start' },
+    send: { method: 'POST', path: '/{id}/send' },
+    complete: { method: 'POST', path: '/complete' },
+    read: { method: 'GET', path: '/{id}' },
+};
+/** shared stereo derivation so an optimistic client tile and the server agree */
+export const uploadStereoOf = (contentType) => {
+    const type = contentType.toLowerCase().split(';')[0].trim();
+    if (type.startsWith('image/'))
+        return UPLOAD_STEREO.image;
+    if (type.startsWith('video/'))
+        return UPLOAD_STEREO.video;
+    if (type.startsWith('audio/'))
+        return UPLOAD_STEREO.sound;
+    if (type === 'application/pdf')
+        return UPLOAD_STEREO.docs;
+    return undefined;
+};
+//# sourceMappingURL=types.js.map

package/dist/esm/upload/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/upload/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,6BAA6B;AAC7B,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACN,CAAC;AAGX,4FAA4F;AAC5F,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,2DAA2D;IAC3D,OAAO,EAAE,SAAS;IAClB,oCAAoC;IACpC,MAAM,EAAE,QAAQ;IAChB,oDAAoD;IACpD,MAAM,EAAE,QAAQ;CACV,CAAC;AAGX,wGAAwG;AACxG,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,0DAA0D;IAC1D,MAAM,EAAE,QAAQ;IAChB,4EAA4E;IAC5E,YAAY,EAAE,eAAe;CACvB,CAAC;AAoEX,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAc,EAA0B,EAAE,CACrE,MAAM,CAAC,MAAM,KAAK,aAAa,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC;AA0E9G,6BAA6B;AAC7B,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACjC,4CAA4C;IAC5C,GAAG,EAAE,KAAK;IACV,kEAAkE;IAClE,OAAO,EAAE,SAAS;IAClB,sDAAsD;IACtD,MAAM,EAAE,QAAQ;CACV,CAAC;AAGX,oFAAoF;AACpF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAC/B,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,WAAW;IACrB,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,gBAAgB;IAC/B,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;CACZ,CAAC;AA+CX,qGAAqG;AACrG,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE;IACzC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE;IAC5C,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE;IAC/C,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE;CAChC,CAAC;AAEX,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,WAAmB,EAA4B,EAAE;IAC5E,MAAM,IAAI,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC;IAC1D,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC;IAC1D,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC;IAC1D,IAAI,IAAI,KAAK,iBAAiB;QAAE,OAAO,aAAa,CAAC,IAAI,CAAC;IAC1D,OAAO,SAAS,CAAC;AACrB,CAAC,CAAC"}

package/dist/upload/engine/engine.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `upload/engine/engine.ts`
+ * - the one upload flow every shell shares: `start` -> run executors -> `complete`.
+ * - swapping the server's transfer method never touches this file; a new `UploadTransfer` kind
+ *   arrives as one more `UploadTransferExecutor` passed to the constructor.
+ * - runtime-neutral like the contract itself: no Node, DOM, or AWS types. the shell injects the
+ *   three things that are shell-specific — reading bytes (`UploadSource`), the HTTP primitives
+ *   (see `./executors`), and hashing.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import type { Upload, UploadCompleteItem, UploadFailure, UploadSupportable, UploadTransfer } from '../types';
+import type { UploadBatchProgressSink, UploadProgressSink } from './progress';
+/**
+ * one payload of bytes a shell can hand over: the contract's `UploadContent`, with the bytes behind a call.
+ * - the contract's `hash` is a string and this one is a call, so this does not extend `UploadContent`.
+ */
+export interface UploadContentSource {
+    contentType: string;
+    contentSize: number;
+    /** pixel size for image/video; echoed into the intent so a list screen can reserve the box */
+    width?: number;
+    height?: number;
+    /** the whole payload in one call */
+    bytes(): Promise<Uint8Array>;
+    /** sha256 hex(64) when this shell chooses to hash at send time; omit to skip */
+    hash?(): Promise<string | undefined>;
+}
+/** bytes provider; hides DOM `File`, RN uri, Electron path behind one shape */
+export interface UploadSource extends UploadContentSource {
+    name: string;
+    /** a preview this shell already made. the engine sends it beside the original and never derives one */
+    thumbnail?: UploadContentSource;
+}
+/** moves bytes for one transfer kind and reports the receipt the server expects in `complete` */
+export interface UploadTransferExecutor<T extends UploadTransfer = UploadTransfer> {
+    readonly kind: T['kind'];
+    /**
+     * `onProgress` is optional to CALL, not to accept: an executor that cannot observe bytes never calls it.
+     * - `source` is a payload, not a file: the engine passes `source.thumbnail` here too, and that has no `name`.
+     */
+    run(id: string, transfer: T, source: UploadContentSource, onProgress: UploadProgressSink): Promise<UploadCompleteItem>;
+}
+/**
+ * transfers in flight at once.
+ * - a browser queues beyond ~6 per origin, and a queued presigned url burns its `expiresAt` while it waits.
+ * - override per engine when a shell measures something better.
+ */
+export declare const UPLOAD_DEFAULT_CONCURRENCY = 3;
+export declare class UploadEngine {
+    private readonly service;
+    private readonly executors;
+    private readonly options?;
+    private readonly kinds;
+    constructor(service: UploadSupportable, executors: ReadonlyArray<UploadTransferExecutor>, options?: {
+        concurrency?: number;
+    });
+    /** returns one view per source, in order: `stored`, or `failed` with the reason. `onProgress` gets a snapshot per change */
+    upload(sources: ReadonlyArray<UploadSource>, onProgress?: UploadBatchProgressSink): Promise<Upload[]>;
+    private transferTracked;
+    private transfer;
+    private transferOriginal;
+    /**
+     * the preview is subordinate: whatever happens here never reaches `complete`.
+     * - `UploadCompleteItem` is one per upload, so reporting a thumbnail failure would fail the original.
+     * - the server settles the thumbnail by looking at storage at `complete` time, so silence is enough.
+     */
+    private transferThumbnail;
+}
+/** normalize an error thrown by the API adapter */
+export declare const asApiFailure: (error: unknown) => UploadFailure;
+/** normalize a non-2xx answer from the storage endpoint (status 0 = no response) */
+export declare const asStorageFailure: (status: number, code?: string) => UploadFailure;