@streamscloud/kit 0.85.1 → 0.87.0

package/README.md

@@ -15,8 +15,8 @@ without it agent sessions run with no hooks and no shared skills. Re-run after c
 ## Checks
 
 ```sh
-npm run check        # svelte-check + tsc for node files
-npm run lint         # prettier --check + eslint
+npm run check        # the gate: strict svelte-check + tsc for node files + eslint + prettier --check
+npm run lint:fix     # eslint --fix + prettier --write
 ```
 
 ## Release

package/dist/core/files/file-decorators.d.ts

@@ -0,0 +1,3 @@
+import type { BlobWithName, FileWithUploadUrl } from './types';
+export declare const toFileWithUploadUrl: <T extends File>(file: T, uploadUrl: string) => FileWithUploadUrl<T>;
+export declare const toBlobWithName: (blob: Blob, name: string) => BlobWithName;

package/dist/core/files/file-decorators.js

@@ -0,0 +1,2 @@
+export const toFileWithUploadUrl = (file, uploadUrl) => Object.assign(file, { uploadUrl });
+export const toBlobWithName = (blob, name) => Object.assign(blob, { name });

package/dist/core/files/file-validation-rules.d.ts

@@ -1,4 +1,5 @@
 import type { AspectRatioBound, FileValidationRule, VideoOrientationValue } from './file-validation-types';
+import type { ResizeLimits } from './types';
 /**
  * Built-in rule factories. Each takes a constraint and an optional `message`; when omitted, the
  * rule falls back to a localized default from `FileValidationLocalization` (kit ships no English
@@ -21,10 +22,7 @@ export declare const FileRules: {
     AudioDuration: (maxSeconds: number, message?: string) => FileValidationRule;
     AudioOnly: (message?: string) => FileValidationRule;
     Extensions: (extensions: string[], message?: string) => FileValidationRule;
-    ImageDimensions: (limits: {
-        max1: number;
-        max2: number;
-    }, message?: string) => FileValidationRule;
+    ImageDimensions: (limits: ResizeLimits, message?: string) => FileValidationRule;
     ImageMinDimensions: (limits: {
         min1: number;
         min2: number;
@@ -55,9 +53,6 @@ export declare const FileRules: {
     VideoOrientation: (orientation: VideoOrientationValue, message?: string, options?: {
         tolerancePercent?: number;
     }) => FileValidationRule;
-    VideoDimensions: (limits: {
-        max1: number;
-        max2: number;
-    }, message?: string) => FileValidationRule;
+    VideoDimensions: (limits: ResizeLimits, message?: string) => FileValidationRule;
     VideoDuration: (maxSeconds: number, message?: string) => FileValidationRule;
 };

package/dist/core/files/file-with-blob-data-helper.d.ts

@@ -1,4 +1,4 @@
-import { type BlobWithName, type FileWithBlobUrl } from './types';
+import type { BlobWithName, FileWithBlobUrl } from './types';
 type FileGenerationOptions = {
     id?: string;
     maxNameLength?: number;

package/dist/core/files/file-with-blob-data-helper.js

@@ -1,7 +1,7 @@
 import { Base64Helper } from './base64-helper';
+import { toBlobWithName } from './file-decorators';
 import { FileHelper } from './file-helper';
 import { fetchFile } from './file-service';
-import { toBlobWithName } from './types';
 import { default as mime } from 'mime';
 import { nanoid } from 'nanoid';
 export class FileWithBlobDataHelper {

package/dist/core/files/image-resizer.d.ts

@@ -1,31 +1,19 @@
-import type { BlobWithName } from './types';
-export declare const resizeImage: <T extends File>(file: T, limits: {
-    max1: number;
-    max2: number;
-}) => Promise<BlobWithName>;
+import type { ResizedBlob, ResizeLimits, SizedFile } from './types';
+export declare const DEFAULT_RESIZE_LIMITS: Readonly<ResizeLimits>;
+type PixelSize = {
+    width: number;
+    height: number;
+};
+/** `size` rounded down to whole pixels, at least one per side. */
+export declare const toPixelSize: (size: PixelSize) => PixelSize;
+/** `size` downscaled, keeping its aspect ratio, until it fits `limits` (never enlarged), in whole pixels. */
+export declare const fitSize: (size: PixelSize, limits: ResizeLimits) => PixelSize;
+/** `resizeBlob` for a file: always a new `File` under the source's name, with its size. */
+export declare const resizeImage: (file: File, limits: ResizeLimits) => Promise<SizedFile>;
 /**
- * Resizes an image while maintaining its aspect ratio, ensuring that both dimensions fit within the given constraints.
- *
- * The function takes two numeric constraints (`max1` and `max2`) and determines which one applies to the long side
- * and which one applies to the short side of the image.
- *
- * - If the image already fits within the constraints (both sides are within their respective limits),
- *   it is returned unchanged.
- * - If both constraints are provided, the image is resized so that the long side matches its limit.
- *   However, if this causes the short side to exceed its limit, the short side constraint is applied instead.
- * - If only one constraint is provided, it is applied to the longer side, and the other side is scaled proportionally.
- * - If both constraints are zero or negative, the original image is returned without modifications.
- *
- * @param blob - The original image as a `Blob` object.
- * @param limits - An object containing two numeric constraints, `max1` and `max2`.
- *   - **`max1`** - One of the two size constraints.
- *   - **`max2`** - The second size constraint.
- *     **Note:** `max1` and `max2` are not tied to specific dimensions (width or height).
- *     The function determines which one applies to the long side and which to the short side.
- *
- * @returns A promise that resolves to a new resized `Blob` object, or the original `Blob` if resizing is not needed.
+ * Downscales an image, keeping its aspect ratio, until both sides fit `limits` (see `ResizeLimits`).
+ * Only JPEG, PNG and WebP are re-encoded; an image that already fits, or of any other type (SVG, GIF, …),
+ * comes back as the very same `Blob`. Either way the result carries the image's pixel size.
  */
-export declare const resizeBlob: <T extends Blob>(blob: T, limits: {
-    max1: number;
-    max2: number;
-}) => Promise<Blob>;
+export declare const resizeBlob: (blob: Blob, limits: ResizeLimits) => Promise<ResizedBlob>;
+export {};

package/dist/core/files/image-resizer.js

@@ -1,70 +1,40 @@
-let cachedCanvas = null;
-const getCanvas = () => (cachedCanvas ??= document.createElement('canvas'));
+export const DEFAULT_RESIZE_LIMITS = Object.freeze({ max1: 1600, max2: 1000 });
+const RESIZABLE_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp']);
+// A scaled side lands a hair under a whole number (999.9999999999999); a bare floor would drop a pixel.
+const PIXEL_EPSILON = 1e-6;
+/** `size` rounded down to whole pixels, at least one per side. */
+export const toPixelSize = (size) => ({
+    width: Math.max(1, Math.floor(size.width + PIXEL_EPSILON)),
+    height: Math.max(1, Math.floor(size.height + PIXEL_EPSILON))
+});
+/** `size` downscaled, keeping its aspect ratio, until it fits `limits` (never enlarged), in whole pixels. */
+export const fitSize = (size, limits) => {
+    const [longMax, shortMax] = limits.max1 >= limits.max2 ? [limits.max1, limits.max2] : [limits.max2, limits.max1];
+    const scale = Math.min(1, longMax / Math.max(size.width, size.height), shortMax / Math.min(size.width, size.height));
+    return toPixelSize({ width: size.width * scale, height: size.height * scale });
+};
+/** `resizeBlob` for a file: always a new `File` under the source's name, with its size. */
 export const resizeImage = async (file, limits) => {
-    const blob = await resizeBlob(file, limits);
-    const result = blob;
-    if (!(blob instanceof File)) {
-        result.name = file.name;
-    }
-    return result;
+    const { blob, width, height } = await resizeBlob(file, limits);
+    return Object.assign(new File([blob], file.name, { type: blob.type }), { width, height });
 };
 /**
- * Resizes an image while maintaining its aspect ratio, ensuring that both dimensions fit within the given constraints.
- *
- * The function takes two numeric constraints (`max1` and `max2`) and determines which one applies to the long side
- * and which one applies to the short side of the image.
- *
- * - If the image already fits within the constraints (both sides are within their respective limits),
- *   it is returned unchanged.
- * - If both constraints are provided, the image is resized so that the long side matches its limit.
- *   However, if this causes the short side to exceed its limit, the short side constraint is applied instead.
- * - If only one constraint is provided, it is applied to the longer side, and the other side is scaled proportionally.
- * - If both constraints are zero or negative, the original image is returned without modifications.
- *
- * @param blob - The original image as a `Blob` object.
- * @param limits - An object containing two numeric constraints, `max1` and `max2`.
- *   - **`max1`** - One of the two size constraints.
- *   - **`max2`** - The second size constraint.
- *     **Note:** `max1` and `max2` are not tied to specific dimensions (width or height).
- *     The function determines which one applies to the long side and which to the short side.
- *
- * @returns A promise that resolves to a new resized `Blob` object, or the original `Blob` if resizing is not needed.
+ * Downscales an image, keeping its aspect ratio, until both sides fit `limits` (see `ResizeLimits`).
+ * Only JPEG, PNG and WebP are re-encoded; an image that already fits, or of any other type (SVG, GIF, …),
+ * comes back as the very same `Blob`. Either way the result carries the image's pixel size.
  */
 export const resizeBlob = (blob, limits) => {
-    const { max1, max2 } = limits;
-    if (max1 <= 0 && max2 <= 0) {
-        return Promise.resolve(blob);
-    }
     return new Promise((resolve, reject) => {
         const image = new Image();
         image.src = URL.createObjectURL(blob);
         image.onload = () => {
             const { width, height } = image;
-            const isHorizontal = width > height;
-            const originalLongSide = isHorizontal ? width : height;
-            const originalShortSide = isHorizontal ? height : width;
-            const [longSideMax, shortSideMax] = max1 >= max2 ? [max1, max2] : [max2, max1];
-            if (longSideMax > 0 && originalLongSide <= longSideMax && shortSideMax > 0 && originalShortSide <= shortSideMax) {
-                URL.revokeObjectURL(image.src);
-                return resolve(blob);
-            }
-            let newLongSide = Math.min(originalLongSide, longSideMax);
-            let newShortSide = originalShortSide * (newLongSide / originalLongSide);
-            if (shortSideMax > 0 && newShortSide > shortSideMax) {
-                const reducer = newShortSide / shortSideMax;
-                newShortSide = shortSideMax;
-                newLongSide = newLongSide / reducer;
-            }
-            newLongSide = Math.floor(newLongSide);
-            newShortSide = Math.floor(newShortSide);
-            // Skip resize if dimensions unchanged (avoids lossy re-encoding)
-            if (newLongSide === originalLongSide && newShortSide === originalShortSide) {
+            const { width: newWidth, height: newHeight } = fitSize({ width, height }, limits);
+            if (!RESIZABLE_TYPES.has(blob.type) || (newWidth === width && newHeight === height)) {
                 URL.revokeObjectURL(image.src);
-                return resolve(blob);
+                return resolve({ blob, width, height });
             }
-            const newWidth = isHorizontal ? newLongSide : newShortSide;
-            const newHeight = isHorizontal ? newShortSide : newLongSide;
-            const canvas = getCanvas();
+            const canvas = document.createElement('canvas');
             canvas.width = newWidth;
             canvas.height = newHeight;
             const ctx = canvas.getContext('2d');
@@ -75,9 +45,12 @@ export const resizeBlob = (blob, limits) => {
             ctx.drawImage(image, 0, 0, newWidth, newHeight);
             canvas.toBlob((resizedBlob) => {
                 URL.revokeObjectURL(image.src);
-                ctx.clearRect(0, 0, canvas.width, canvas.height);
+                // Safari caps total canvas memory and holds a dropped canvas until GC; shrinking it to 1×1 releases it now.
+                canvas.width = 1;
+                canvas.height = 1;
+                ctx.clearRect(0, 0, 1, 1);
                 if (resizedBlob) {
-                    resolve(resizedBlob);
+                    resolve({ blob: resizedBlob, width: newWidth, height: newHeight });
                 }
                 else {
                     reject(new Error('Failed to create blob from canvas'));

package/dist/core/files/index.d.ts

@@ -1,16 +1,16 @@
-export type { BlobWithName, FileWithBlobUrl, FileWithUploadUrl } from './types';
+export type { BlobWithName, FileWithBlobUrl, FileWithUploadUrl, ResizedBlob, ResizeLimits, SizedFile } from './types';
 export type { AspectRatioBound, FileValidationResult, FileValidationRule, FileValidationRuleSets, VideoOrientationValue } from './file-validation-types';
 export type { BlobUpload, BlobUploadStrategy, PreviewableUploadingFile, UploadPreviewMode, UploadingFile, UploadingFileStatus } from './upload-types';
-export type { AddOptions, UploadMediaStoreOptions } from './upload-media-store.svelte';
+export type { AddOptions, UploadMediaStoreOptions, UploadOutcome } from './upload-media-store.svelte';
 export type { FileTypeCheck } from './file-helper';
-export { toBlobWithName, toFileWithUploadUrl } from './types';
+export { toBlobWithName, toFileWithUploadUrl } from './file-decorators';
 export { uploadBlob } from './blob-storage';
 export { openFile } from './open-file';
 export { FileHelper } from './file-helper';
 export { downloadBlob, downloadFromUrl, downloadJson, fetchFile } from './file-service';
 export { AcceptFileType, isPreviewableType, matchesAcceptedFileTypes } from './file-types';
 export { deriveAccept } from './file-validation-rule-sets';
-export { resizeBlob, resizeImage } from './image-resizer';
+export { DEFAULT_RESIZE_LIMITS, fitSize, resizeBlob, resizeImage, toPixelSize } from './image-resizer';
 export { FileWithBlobDataHelper } from './file-with-blob-data-helper';
 export { FilesProvider } from './files-provider';
 export { FileValidator } from './file-validator';

package/dist/core/files/index.js

@@ -1,12 +1,12 @@
 // Utilities
-export { toBlobWithName, toFileWithUploadUrl } from './types';
+export { toBlobWithName, toFileWithUploadUrl } from './file-decorators';
 export { uploadBlob } from './blob-storage';
 export { openFile } from './open-file';
 export { FileHelper } from './file-helper';
 export { downloadBlob, downloadFromUrl, downloadJson, fetchFile } from './file-service';
 export { AcceptFileType, isPreviewableType, matchesAcceptedFileTypes } from './file-types';
 export { deriveAccept } from './file-validation-rule-sets';
-export { resizeBlob, resizeImage } from './image-resizer';
+export { DEFAULT_RESIZE_LIMITS, fitSize, resizeBlob, resizeImage, toPixelSize } from './image-resizer';
 export { FileWithBlobDataHelper } from './file-with-blob-data-helper';
 export { FilesProvider } from './files-provider';
 export { FileValidator } from './file-validator';

package/dist/core/files/types.d.ts

@@ -2,11 +2,23 @@ export type FileWithBlobUrl = File & {
     blobUrl: string;
     id: string;
 };
+export type SizedFile = File & {
+    width: number;
+    height: number;
+};
+/** Two positive pixel limits not tied to width / height — the image's longer side fits the larger one, its shorter side the smaller. */
+export type ResizeLimits = {
+    max1: number;
+    max2: number;
+};
+export type ResizedBlob = {
+    blob: Blob;
+    width: number;
+    height: number;
+};
 export type FileWithUploadUrl<T extends File = File> = T & {
     uploadUrl: string;
 };
-export declare const toFileWithUploadUrl: <T extends File>(file: T, uploadUrl: string) => FileWithUploadUrl<T>;
 export type BlobWithName = Blob & {
     name: string;
 };
-export declare const toBlobWithName: (blob: Blob, name: string) => BlobWithName;

package/dist/core/files/types.js

@@ -1,10 +1 @@
-export const toFileWithUploadUrl = (file, uploadUrl) => {
-    const fileWithUploadUrl = file;
-    fileWithUploadUrl.uploadUrl = uploadUrl;
-    return fileWithUploadUrl;
-};
-export const toBlobWithName = (blob, name) => {
-    const blobWithName = blob;
-    blobWithName.name = name;
-    return blobWithName;
-};
+export {};

package/dist/core/files/upload-media-store.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { ResizeLimits } from './types';
 import type { BlobUploadStrategy, PreviewableUploadingFile, UploadPreviewMode, UploadingFile } from './upload-types';
 type SuccessfulUpload = Extract<UploadingFile, {
     status: 'success';
@@ -16,15 +17,8 @@ export type UploadOutcome = {
     succeeded: SuccessfulUpload[];
 };
 export type UploadMediaStoreOptions = {
-    /**
-     * Auto-resize images before upload. Pass `false` to disable; pass an object to override the
-     * defaults. `max1` / `max2` are not tied to width / height — the longer side is matched to
-     * the larger limit. @default `{ max1: 1600, max2: 1000 }`
-     */
-    resize?: {
-        max1: number;
-        max2: number;
-    } | false;
+    /** Downscale images to these limits before upload; `false` uploads them as they are. @default DEFAULT_RESIZE_LIMITS (1600 / 1000) */
+    resize?: ResizeLimits | false;
     /** Parallel upload limit. @default 20 */
     concurrency?: number;
     on?: {
@@ -62,7 +56,7 @@ export declare class UploadMediaStore {
     private _inFlight;
     private _nextRunId;
     private _strategy;
-    private opts;
+    private _opts;
     constructor(strategy: BlobUploadStrategy, opts?: UploadMediaStoreOptions);
     /** Reactive read of the queue. */
     get files(): UploadingFile[];
@@ -102,12 +96,12 @@ export declare class UploadMediaStore {
      * with no extra wiring.
      */
     upload(): Promise<UploadOutcome>;
-    private outcome;
-    private settled;
-    private runQueued;
-    private maybeResize;
-    private fail;
-    private failAll;
-    private transition;
+    private _outcome;
+    private _settled;
+    private _runQueued;
+    private _maybeResize;
+    private _fail;
+    private _failAll;
+    private _transition;
 }
 export {};

package/dist/core/files/upload-media-store.svelte.js

@@ -1,10 +1,9 @@
 import { AppUploadActivity } from './app-upload-activity.svelte';
 import { uploadBlob } from './blob-storage';
 import { isPreviewableType } from './file-types';
-import { resizeBlob } from './image-resizer';
+import { DEFAULT_RESIZE_LIMITS, resizeBlob } from './image-resizer';
 import { nanoid } from 'nanoid';
 import { default as pLimit } from 'p-limit';
-const DEFAULT_RESIZE_LIMITS = { max1: 1600, max2: 1000 };
 const DEFAULT_CONCURRENCY = 20;
 const toPreviewUrl = (file, mode) => mode === 'always' || (mode === 'mime' && isPreviewableType(file.type)) ? URL.createObjectURL(file) : null;
 const revokePreviewUrl = (file) => {
@@ -38,10 +37,10 @@ export class UploadMediaStore {
     _inFlight = new Map();
     _nextRunId = 0;
     _strategy;
-    opts;
+    _opts;
     constructor(strategy, opts = {}) {
         this._strategy = strategy;
-        this.opts = opts;
+        this._opts = opts;
     }
     /** Reactive read of the queue. */
     get files() {
@@ -89,19 +88,19 @@ export class UploadMediaStore {
     async upload() {
         const queued = this._files.filter((f) => f.status === 'queued' || f.status === 'error');
         if (queued.length === 0) {
-            await this.settled();
-            return this.outcome();
+            await this._settled();
+            return this._outcome();
         }
         // Claim before the first await, or a second upload() during the strategy call re-claims the same files.
         for (const entry of queued) {
-            this.transition(entry.id, (f) => ({ id: f.id, file: f.file, progress: 0, previewUrl: f.previewUrl, status: 'uploading' }));
+            this._transition(entry.id, (f) => ({ id: f.id, file: f.file, progress: 0, previewUrl: f.previewUrl, status: 'uploading' }));
         }
         const fileIds = new Set(queued.map((f) => f.id));
         const activityRunId = AppUploadActivity.beginRun(() => this._files.filter((f) => fileIds.has(f.id)));
         const runId = this._nextRunId++;
         const run = (async () => {
             try {
-                await this.runQueued(queued);
+                await this._runQueued(queued);
             }
             finally {
                 AppUploadActivity.endRun(activityRunId);
@@ -109,43 +108,43 @@ export class UploadMediaStore {
             }
         })();
         this._inFlight.set(runId, run);
-        await this.settled();
-        return this.outcome();
+        await this._settled();
+        return this._outcome();
     }
-    outcome() {
+    _outcome() {
         return {
             failed: this._files.filter((f) => f.status === 'error'),
             succeeded: this._files.filter((f) => f.status === 'success')
         };
     }
-    async settled() {
+    async _settled() {
         while (this._inFlight.size > 0) {
             await Promise.all([...this._inFlight.values()]);
         }
     }
-    async runQueued(queued) {
+    async _runQueued(queued) {
         let presigned;
         try {
             presigned = await this._strategy(queued.length);
         }
         catch (error) {
-            this.failAll(queued, error);
+            this._failAll(queued, error);
             return;
         }
         if (presigned.length < queued.length) {
-            this.failAll(queued, new Error(`BlobUploadStrategy returned ${presigned.length} slots for ${queued.length} files`));
+            this._failAll(queued, new Error(`BlobUploadStrategy returned ${presigned.length} slots for ${queued.length} files`));
             return;
         }
-        const limit = pLimit(this.opts.concurrency ?? DEFAULT_CONCURRENCY);
-        const resizeOpt = this.opts.resize;
+        const limit = pLimit(this._opts.concurrency ?? DEFAULT_CONCURRENCY);
+        const resizeOpt = this._opts.resize;
         await Promise.all(queued.map((entry, i) => limit(async () => {
             try {
-                const blob = resizeOpt === false ? entry.file : await this.maybeResize(entry.file, resizeOpt ?? DEFAULT_RESIZE_LIMITS);
+                const blob = resizeOpt === false ? entry.file : await this._maybeResize(entry.file, resizeOpt ?? DEFAULT_RESIZE_LIMITS);
                 const slot = presigned[i];
                 await uploadBlob(slot.uploadUrl, blob, (loaded, total) => {
-                    this.transition(entry.id, (f) => (f.status === 'uploading' ? { ...f, progress: total > 0 ? loaded / total : 0 } : f));
+                    this._transition(entry.id, (f) => (f.status === 'uploading' ? { ...f, progress: total > 0 ? loaded / total : 0 } : f));
                 });
-                const done = this.transition(entry.id, (f) => ({
+                const done = this._transition(entry.id, (f) => ({
                     id: f.id,
                     file: f.file,
                     progress: 1,
@@ -155,42 +154,40 @@ export class UploadMediaStore {
                     readUrl: slot.readUrl
                 }));
                 if (done?.status === 'success') {
-                    this.opts.on?.blobId?.(done, slot.id);
+                    this._opts.on?.blobId?.(done, slot.id);
                 }
             }
             catch (error) {
-                this.fail(entry.id, error);
+                this._fail(entry.id, error);
             }
         })));
-        this.opts.on?.done?.();
+        this._opts.on?.done?.();
     }
-    async maybeResize(file, limits) {
-        // Only resize images — leave other media alone.
-        if (!file.type.startsWith('image/') || file.type === 'image/gif') {
+    async _maybeResize(file, limits) {
+        if (!file.type.startsWith('image/')) {
             return file;
         }
         try {
-            return await resizeBlob(file, limits);
+            return (await resizeBlob(file, limits)).blob;
         }
         catch {
-            // Resize is best-effort: fall back to the original on failure (e.g. corrupt file).
             return file;
         }
     }
-    fail(id, error) {
+    _fail(id, error) {
         const message = error instanceof Error ? error.message : 'Upload failed';
-        const failed = this.transition(id, (f) => ({ id: f.id, file: f.file, progress: f.progress, previewUrl: f.previewUrl, status: 'error', error: message }));
+        const failed = this._transition(id, (f) => ({ id: f.id, file: f.file, progress: f.progress, previewUrl: f.previewUrl, status: 'error', error: message }));
         if (failed?.status === 'error') {
-            this.opts.on?.error?.(failed, error);
+            this._opts.on?.error?.(failed, error);
         }
     }
-    failAll(files, error) {
+    _failAll(files, error) {
         for (const entry of files) {
-            this.fail(entry.id, error);
+            this._fail(entry.id, error);
         }
-        this.opts.on?.done?.();
+        this._opts.on?.done?.();
     }
-    transition(id, next) {
+    _transition(id, next) {
         let updated;
         this._files = this._files.map((f) => {
             if (f.id !== id) {

package/dist/styles/_mixins.scss

@@ -82,14 +82,24 @@
   max-height: 100%;
 }
 
-@mixin scrollbar($thumb-color: var(--scrollbar--thumb-color, light-dark(#d1d5db, #4b5563)), $track-color: var(--scrollbar--track-color, transparent)) {
+@mixin scrollbar(
+  $thumb-color: var(--scrollbar--thumb-color, light-dark(#d1d5db, #4b5563)),
+  $track-color: var(--scrollbar--track-color, transparent),
+  $size: 6px,
+  $symmetric: null
+) {
   --_cross-browser-scrollbar--thumb-color: #{$thumb-color};
   --_cross-browser-scrollbar--track-color: #{$track-color};
 
-  @include _cross-browser-scrollbar;
+  @include _cross-browser-scrollbar($size, $symmetric);
 }
 
-@mixin scrollbar-on-hover($thumb-color: var(--scrollbar--thumb-color, light-dark(#d1d5db, #4b5563)), $track-color: var(--scrollbar--track-color, transparent)) {
+@mixin scrollbar-on-hover(
+  $thumb-color: var(--scrollbar--thumb-color, light-dark(#d1d5db, #4b5563)),
+  $track-color: var(--scrollbar--track-color, transparent),
+  $size: 6px,
+  $symmetric: null
+) {
   --_cross-browser-scrollbar--thumb-color: transparent;
   --_cross-browser-scrollbar--track-color: transparent;
 
@@ -98,29 +108,73 @@
     --_cross-browser-scrollbar--track-color: #{$track-color};
   }
 
-  @include _cross-browser-scrollbar;
+  @include _cross-browser-scrollbar($size, $symmetric);
 }
 
-@mixin _cross-browser-scrollbar {
-  &::-webkit-scrollbar {
-    width: 6px;
-    height: 6px;
-  }
+@mixin _cross-browser-scrollbar($size, $symmetric) {
+  --_cross-browser-scrollbar--gutter: 0px;
 
-  &::-webkit-scrollbar-track {
-    background: var(--_cross-browser-scrollbar--track-color);
-    border-radius: 100vw;
-  }
+  // a non-auto scrollbar-color / scrollbar-width (own or inherited) makes WebKit / Blink drop the 6px pseudo-element bar for the wider platform one
+  @include when-scrollbar-sizable {
+    scrollbar-color: auto;
+    scrollbar-width: auto;
+
+    &::-webkit-scrollbar {
+      width: $size;
+      height: $size;
+    }
+
+    &::-webkit-scrollbar-track {
+      background: var(--_cross-browser-scrollbar--track-color);
+      border-radius: 100vw;
+    }
 
-  &::-webkit-scrollbar-thumb {
-    background: var(--_cross-browser-scrollbar--thumb-color);
-    border-radius: 100vw;
+    &::-webkit-scrollbar-thumb {
+      background: var(--_cross-browser-scrollbar--thumb-color);
+      border-radius: 100vw;
+    }
   }
 
-  @supports (scrollbar-color: transparent transparent) {
+  @include when-scrollbar-unsizable {
     scrollbar-color: var(--_cross-browser-scrollbar--thumb-color) var(--_cross-browser-scrollbar--track-color);
     scrollbar-width: thin;
   }
+
+  // not scrollbar-gutter: both-edges here — Safari reserves both gutters on the end side
+  @if $symmetric {
+    @include when-scrollbar-sizable {
+      --_cross-browser-scrollbar--gutter: #{$size};
+
+      overflow-y: scroll;
+    }
+  }
+
+  @if $symmetric == all {
+    @include when-scrollbar-unsizable {
+      scrollbar-gutter: stable both-edges;
+    }
+  }
+}
+
+@mixin when-scrollbar-sizable {
+  @supports selector(::-webkit-scrollbar) {
+    @content;
+  }
+}
+
+// room to reserve for the platform scrollbar where its width can't be set (~11px thin bar + 1px); never subtract it — overlay scrollbars take 0
+$unsizable-scrollbar-allowance: 12px;
+
+// no ::-webkit-scrollbar (Firefox): the platform bar can't shrink into a panel padding, so a box sized for the 4–6px bar clips its content unless it adds the allowance here
+@mixin when-scrollbar-unsizable {
+  @supports not selector(::-webkit-scrollbar) {
+    @content;
+  }
+}
+
+@mixin scrollbar-padding-inline($padding) {
+  padding-inline-start: max(#{$padding}, var(--_cross-browser-scrollbar--gutter, 0px));
+  padding-inline-end: max(0px, calc(#{$padding} - var(--_cross-browser-scrollbar--gutter, 0px)));
 }
 
 @mixin fade-in-animation($duration: 5s) {