@lazycatcloud/vue-media-preview 0.1.1 → 0.1.2

package/README.md

@@ -65,7 +65,7 @@ import type { PreviewMedia, PreviewAnchor } from '@lazycatcloud/vue-media-previe
 
 详见 [接入与架构](docs/vue-media-preview.md) 和 [测试说明](docs/testing.md)。
 
-大原图通过独立适屏资源预览；默认不直接解码超过 32MiB 或 2400 万像素的原图，未实现瓦片式超大图。真实相册业务与特殊格式边界见接入文档。
+大原图通过独立适屏资源预览；默认原图上限为 32MiB / 6400 万像素，`resourcePolicy.maxOriginalPixels` 同时用于原图请求前检查和实际图片尺寸检查，未实现瓦片式超大图。真实相册业务与特殊格式边界见接入文档。
 
 ## npm 发布
 

package/dist/components/MediaPreview.vue.d.ts

@@ -94,7 +94,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_WithDefaults<__VLS
     closing: () => void;
     change: (index: number) => void;
     close: () => void;
-    ready: (index: number, quality: "thumbnail" | "screen" | "full") => void;
+    ready: (index: number, quality: "full" | "thumbnail" | "screen") => void;
     originalState: (media: PreviewMedia, status: OriginalStatus, reason: string) => void;
     opened: (index: number) => void;
     loadMore: (index: number) => void;
@@ -118,7 +118,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_WithDefaults<__VLS
     };
 }>>> & {
     onError?: ((error: Error, media: PreviewMedia) => any) | undefined;
-    onReady?: ((index: number, quality: "thumbnail" | "screen" | "full") => any) | undefined;
+    onReady?: ((index: number, quality: "full" | "thumbnail" | "screen") => any) | undefined;
     onOriginalState?: ((media: PreviewMedia, status: OriginalStatus, reason: string) => any) | undefined;
     onChange?: ((index: number) => any) | undefined;
     onClose?: (() => any) | undefined;

package/dist/components/PreviewStage.vue.d.ts

@@ -55,13 +55,16 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
     togglePlayback: () => void;
     toggleFullscreen: () => Promise<void>;
     captureFrame: () => {
+        image: HTMLImageElement | ImageBitmap;
+        scale: number;
+    } | {
         image: HTMLCanvasElement | HTMLImageElement | HTMLVideoElement;
         scale: number;
     };
 }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     error: (error: Error) => void;
     close: () => void;
-    ready: (quality: "thumbnail" | "screen" | "full") => void;
+    ready: (quality: "full" | "thumbnail" | "screen") => void;
     originalState: (status: OriginalStatus, reason: string) => void;
     liveState: (status: LivePhotoStatus) => void;
     liveEnded: () => void;
@@ -93,7 +96,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
     paging: boolean;
 }>>> & {
     onError?: ((error: Error) => any) | undefined;
-    onReady?: ((quality: "thumbnail" | "screen" | "full") => any) | undefined;
+    onReady?: ((quality: "full" | "thumbnail" | "screen") => any) | undefined;
     onOriginalState?: ((status: OriginalStatus, reason: string) => any) | undefined;
     onLiveState?: ((status: LivePhotoStatus) => any) | undefined;
     onLiveEnded?: (() => any) | undefined;

package/dist/core/rendering/image.d.ts

@@ -0,0 +1,17 @@
+import type { PreviewRotation, PreviewSize } from "../types";
+export interface ImageFrame {
+    viewport: PreviewSize;
+    size: PreviewSize;
+    offsetX: number;
+    offsetY: number;
+    rotation: PreviewRotation;
+}
+/** Visible rectangle in the unrotated image's rendered CSS pixels. */
+export declare function visibleImageRect(frame: ImageFrame): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Crop before sampling so zoomed originals do not resample offscreen pixels. */
+export declare function drawViewportImage(context: CanvasRenderingContext2D, image: HTMLImageElement | ImageBitmap, frame: ImageFrame, moving: boolean): void;

package/dist/core/resources/bitmap/client.d.ts

@@ -0,0 +1,4 @@
+import type { PreparedBitmaps } from "./types";
+export declare function closeBitmaps({ full, motion }: PreparedBitmaps): void;
+/** Each queued store load owns its worker; cancellation terminates its decode/resize work. */
+export declare function prepareJpegBitmaps(blob: Blob, maxMotionPixels: number, signal: AbortSignal): Promise<PreparedBitmaps>;

package/dist/core/resources/bitmap/decode.worker.d.ts

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

package/dist/core/resources/bitmap/types.d.ts

@@ -0,0 +1,14 @@
+export interface DecodeRequest {
+    blob: Blob;
+    maxMotionPixels: number;
+}
+export interface PreparedBitmaps {
+    full: ImageBitmap;
+    motion: ImageBitmap;
+}
+export type DecodeResult = ({
+    status: "ready";
+} & PreparedBitmaps) | {
+    status: "error";
+    message: string;
+};

package/dist/core/resources/imageLimits.d.ts

@@ -1,6 +1,6 @@
 /** Resource budgets shared by transport, caching and Canvas renderers. */
 export declare const imageLimits: {
-    readonly maxDecodedPixels: 24000000;
+    readonly maxDecodedPixels: 64000000;
     readonly maxCanvasPixels: 6000000;
     readonly maxDevicePixelRatio: 2.5;
     readonly maxOriginalBytes: number;

package/dist/core/resources/imageOwnership.d.ts

@@ -0,0 +1,8 @@
+import type { ImageLease } from "./imageStore";
+/** Request replacement must not release pixels that are still displayed. */
+export declare function createImageOwnership(): {
+    replace(leases: ImageLease[]): void;
+    display(lease: ImageLease): void;
+    clearDisplay(): void;
+    dispose(): void;
+};

package/dist/core/resources/imageRequest.d.ts

@@ -11,5 +11,5 @@ interface ImageRequest {
     originalReason: string;
 }
 /** Decide resource tiers and safety before the renderer acquires any transport leases. */
-export declare function planImageRequest(media: PreviewMedia, requestedQuality: ImageQuality, policy: ImagePolicy, resolveSource: ImageSourceResolver, targetWidth: number): ImageRequest;
+export declare function planImageRequest(media: PreviewMedia, requestedQuality: ImageQuality, policy: ImagePolicy, resolveSource: ImageSourceResolver, targetWidth: number, originalEnabled?: boolean): ImageRequest;
 export {};

package/dist/core/resources/imageResource.d.ts

@@ -0,0 +1,11 @@
+/** The DOM image supplies geometry and the public media handle; Canvas uses the prepared pixel source. */
+export interface ImageResource {
+    image: HTMLImageElement;
+    source: HTMLImageElement | ImageBitmap;
+    motionSource: HTMLImageElement | ImageBitmap;
+    bytes: number;
+    dispose: () => void;
+}
+export declare function imageElementResource(image: HTMLImageElement): ImageResource;
+/** Blob decoding avoids Chromium's scale-dependent lazy JPEG decode during drawImage. */
+export declare function prepareImageResource(image: HTMLImageElement, blob: Blob, signal: AbortSignal): Promise<ImageResource>;

package/dist/core/resources/imageStore.d.ts

@@ -1,11 +1,14 @@
 import type { ImageLoader } from "./imageTransport";
+import type { ImageResource } from "./imageResource";
 export interface ImageLease {
     ready: Promise<HTMLImageElement>;
+    resource: Promise<ImageResource>;
     release: () => void;
 }
 export interface ImageRequestOptions {
     priority?: number;
     maxBytes?: number;
+    maxPixels?: number;
 }
 /** Shared ownership, bounded fetch/decode concurrency and cancellation of unowned requests. */
 export declare class ImageStore {

package/dist/core/resources/imageTransport.d.ts

@@ -1,9 +1,9 @@
-export declare class ImageLimitError extends Error {
-    constructor(message: string);
-}
+import type { ImageResource } from "./imageResource";
+export { ImageLimitError } from "./validation/image";
 export interface ImageLoadOptions {
     signal: AbortSignal;
     readonly maxBytes: number;
+    readonly maxPixels: number;
 }
-export type ImageLoader = (url: string, options: ImageLoadOptions) => Promise<HTMLImageElement>;
+export type ImageLoader = (url: string, options: ImageLoadOptions) => Promise<ImageResource>;
 export declare const loadImage: ImageLoader;

package/dist/core/resources/validation/image.d.ts

@@ -0,0 +1,13 @@
+export declare class ImageLimitError extends Error {
+    constructor(message: string);
+}
+/** Apply the same decoded-pixel boundary to downloads and every cached-resource owner. */
+export declare function assertImagePixels(image: HTMLImageElement, maxPixels: number): void;
+export declare const originalLimitReason = "\u539F\u56FE\u8D85\u8FC7\u8D44\u6E90\u9650\u5236";
+export declare function originalLoadFailure(error: unknown): {
+    status: "blocked";
+    reason: string;
+} | {
+    status: "error";
+    reason: string;
+};

package/dist/core/video/source/session.d.ts

@@ -0,0 +1,8 @@
+import type { PreviewMedia } from "../../types";
+import type { VideoSourceLoader, VideoSourceObserver } from "./types";
+/** Retire callbacks before cleanup can dispatch queued media/transport events. */
+export declare function createVideoSourceSession(observer: VideoSourceObserver): {
+    clear: () => void;
+    dispose: () => void;
+    start(video: HTMLVideoElement, media: PreviewMedia, loader: VideoSourceLoader): void;
+};

package/dist/core/video/source/types.d.ts

@@ -0,0 +1,8 @@
+import type { PreviewMedia } from "../../types";
+/** Hosts own transport; the component owns playback and the effective timeline. */
+export type VideoSourceLoader = (video: HTMLVideoElement, media: PreviewMedia, reportError: (error: Error) => void, reportDuration: (seconds: number) => void) => () => void;
+export interface VideoSourceObserver {
+    error: (error: Error) => void;
+    duration: (seconds: number) => void;
+    reset: () => void;
+}

package/dist/core/video/timeline/buffered.d.ts

@@ -0,0 +1,12 @@
+export interface BufferedRange {
+    start: number;
+    end: number;
+}
+export type CompletedBuffer = {
+    kind: "pending";
+} | {
+    kind: "retained";
+    end: number;
+};
+/** Preserve holes and normalize the retained tail once playback has reached its end. */
+export declare function readBufferedRanges(video: HTMLVideoElement, duration: number, completed: CompletedBuffer): BufferedRange[];

package/dist/core/video/timeline/index.d.ts

@@ -0,0 +1,15 @@
+import { type BufferedRange } from "./buffered";
+export interface VideoTimelineSnapshot {
+    duration: number;
+    time: number;
+    buffered: number;
+    bufferedRanges: BufferedRange[];
+}
+export declare function emptyVideoTimeline(): VideoTimelineSnapshot;
+/** One source of timing truth for text, seek bounds, playback and retained buffers. */
+export declare function createVideoTimeline(): {
+    setDuration(seconds: number): void;
+    complete(video: HTMLVideoElement): void;
+    reset(): void;
+    read(video: HTMLVideoElement, ended: boolean): VideoTimelineSnapshot;
+};

package/dist/core/video/timeline/time.d.ts

@@ -0,0 +1,3 @@
+/** UI text truncates seconds; timeline calculations retain their fractional precision. */
+export declare function formatVideoTime(seconds: number): string;
+export declare function finiteDuration(seconds: number): number;

package/dist/core/video/useVideoPlayback.d.ts

@@ -1,22 +1,30 @@
-export declare function formatVideoTime(seconds: number): string;
+export { formatVideoTime } from "./timeline/time";
 /** Playback owns media state; the preview still owns navigation and transitions. */
 export declare function useVideoPlayback(video: () => HTMLVideoElement, reportError: (error: Error) => void): {
     state: {
-        playing: boolean;
-        buffering: boolean;
-        duration: number;
-        time: number;
-        buffered: number;
         muted: boolean;
         ended: boolean;
         scrubbing: boolean;
         scrubTime: number;
         status: "loading" | "ready" | "error";
+        duration: number;
+        time: number;
+        buffered: number;
+        bufferedRanges: {
+            start: number;
+            end: number;
+        }[];
+        playing: boolean;
+        buffering: boolean;
     };
     seekable: import("vue").ComputedRef<boolean>;
     displayTime: import("vue").ComputedRef<number>;
     progress: import("vue").ComputedRef<number>;
     bufferedProgress: import("vue").ComputedRef<number>;
+    bufferedRanges: import("vue").ComputedRef<{
+        left: number;
+        width: number;
+    }[]>;
     events: {
         loadedmetadata: () => void;
         durationchange: () => void;
@@ -24,6 +32,7 @@ export declare function useVideoPlayback(video: () => HTMLVideoElement, reportEr
         progress: () => void;
         loadeddata: () => void;
         canplay: () => void;
+        canplaythrough: () => void;
         play: () => void;
         playing: () => void;
         pause: () => void;
@@ -42,5 +51,12 @@ export declare function useVideoPlayback(video: () => HTMLVideoElement, reportEr
     endScrub: (commit?: boolean) => void;
     toggleMuted: () => void;
     retry: () => void;
+    setSourceDuration: (seconds: number) => void;
+    resetSource: () => void;
+    sourceObserver: {
+        error: (error: Error) => void;
+        duration: (seconds: number) => void;
+        reset: () => void;
+    };
     dispose: () => void;
 };

package/dist/core/video/useVideoSource.d.ts

@@ -1,5 +1,5 @@
 import type { PreviewMedia } from "../types";
-/** A host can attach its own streaming transport without coupling the renderer to it. */
-export type VideoSourceLoader = (video: HTMLVideoElement, media: PreviewMedia, reportError: (error: Error) => void) => () => void;
+import type { VideoSourceLoader, VideoSourceObserver } from "./source/types";
+export type { VideoSourceLoader } from "./source/types";
 export declare const nativeVideoSource: VideoSourceLoader;
-export declare function useVideoSource(video: () => HTMLVideoElement, media: () => PreviewMedia, enabled: () => boolean, loader: () => VideoSourceLoader, reportError: (error: Error) => void): () => number;
+export declare function useVideoSource(video: () => HTMLVideoElement, media: () => PreviewMedia, enabled: () => boolean, loader: () => VideoSourceLoader, observer: VideoSourceObserver): () => number;

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { default as VirtualTimeline } from "./components/VirtualTimeline.vue";
 export { defaultImagePolicy, defaultImageSource } from "./core/resources/imagePolicy";
 export type { ImagePolicy, ImageSourceResolver, ImageQuality, OriginalStatus, } from "./core/resources/imagePolicy";
 export { previewImageStore, ImageStore } from "./core/resources/imageStore";
+export type { ImageLease, ImageRequestOptions } from "./core/resources/imageStore";
+export type { ImageResource } from "./core/resources/imageResource";
 export type { TimelineGroup, VirtualTimelineHandle } from "./core/timeline/layout";
 export { nativeVideoSource } from "./core/video/useVideoSource";
 export type { VideoSourceLoader } from "./core/video/useVideoSource";

package/dist/renderers/ImageCanvasRenderer.vue.d.ts

@@ -8,6 +8,7 @@ type __VLS_Props = {
     rendering?: boolean;
     requestVersion?: number;
     loadEnabled?: boolean;
+    originalEnabled?: boolean;
     priority?: number;
     resourcePolicy?: ImagePolicy;
     resolveSource?: ImageSourceResolver;
@@ -18,32 +19,40 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
     initialImage: () => InitialImage;
     rendering: boolean;
     loadEnabled: boolean;
+    originalEnabled: boolean;
     requestVersion: number;
     priority: number;
     resourcePolicy: () => ImagePolicy;
     resolveSource: ImageSourceResolver;
-}>, unknown, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+}>, {
+    captureFrame: () => {
+        image: HTMLImageElement | ImageBitmap;
+        scale: number;
+    };
+}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     error: (error: Error) => void;
-    ready: (quality: "thumbnail" | "screen" | "full") => void;
+    ready: (quality: "full" | "thumbnail" | "screen") => void;
     originalState: (status: OriginalStatus, reason: string) => void;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
     quality: string;
     initialImage: () => InitialImage;
     rendering: boolean;
     loadEnabled: boolean;
+    originalEnabled: boolean;
     requestVersion: number;
     priority: number;
     resourcePolicy: () => ImagePolicy;
     resolveSource: ImageSourceResolver;
 }>>> & {
     onError?: ((error: Error) => any) | undefined;
-    onReady?: ((quality: "thumbnail" | "screen" | "full") => any) | undefined;
+    onReady?: ((quality: "full" | "thumbnail" | "screen") => any) | undefined;
     onOriginalState?: ((status: OriginalStatus, reason: string) => any) | undefined;
 }, {
     quality: ImageQuality;
     rendering: boolean;
     requestVersion: number;
     loadEnabled: boolean;
+    originalEnabled: boolean;
     priority: number;
     resourcePolicy: ImagePolicy;
     resolveSource: ImageSourceResolver;

package/dist/renderers/LivePhotoRenderer.vue.d.ts

@@ -37,7 +37,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
     captureFrame: typeof captureFrame;
 }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     error: (error: Error) => void;
-    ready: (quality: "thumbnail" | "screen" | "full") => void;
+    ready: (quality: "full" | "thumbnail" | "screen") => void;
     originalState: (status: OriginalStatus, reason: string) => void;
     liveState: (status: LivePhotoStatus) => void;
     liveEnded: () => void;
@@ -55,7 +55,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
     resolveSource: ImageSourceResolver;
 }>>> & {
     onError?: ((error: Error) => any) | undefined;
-    onReady?: ((quality: "thumbnail" | "screen" | "full") => any) | undefined;
+    onReady?: ((quality: "full" | "thumbnail" | "screen") => any) | undefined;
     onOriginalState?: ((status: OriginalStatus, reason: string) => any) | undefined;
     onLiveState?: ((status: LivePhotoStatus) => any) | undefined;
     onLiveEnded?: (() => any) | undefined;

package/dist/renderers/VideoDomRenderer.vue.d.ts

@@ -54,21 +54,29 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
     toggleFullscreen: typeof toggleFullscreen;
     playback: {
         state: {
-            playing: boolean;
-            buffering: boolean;
-            duration: number;
-            time: number;
-            buffered: number;
             muted: boolean;
             ended: boolean;
             scrubbing: boolean;
             scrubTime: number;
             status: "loading" | "ready" | "error";
+            duration: number;
+            time: number;
+            buffered: number;
+            bufferedRanges: {
+                start: number;
+                end: number;
+            }[];
+            playing: boolean;
+            buffering: boolean;
         };
         seekable: import("vue").ComputedRef<boolean>;
         displayTime: import("vue").ComputedRef<number>;
         progress: import("vue").ComputedRef<number>;
         bufferedProgress: import("vue").ComputedRef<number>;
+        bufferedRanges: import("vue").ComputedRef<{
+            left: number;
+            width: number;
+        }[]>;
         events: {
             loadedmetadata: () => void;
             durationchange: () => void;
@@ -76,6 +84,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
             progress: () => void;
             loadeddata: () => void;
             canplay: () => void;
+            canplaythrough: () => void;
             play: () => void;
             playing: () => void;
             pause: () => void;
@@ -94,12 +103,19 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
         endScrub: (commit?: boolean) => void;
         toggleMuted: () => void;
         retry: () => void;
+        setSourceDuration: (seconds: number) => void;
+        resetSource: () => void;
+        sourceObserver: {
+            error: (error: Error) => void;
+            duration: (seconds: number) => void;
+            reset: () => void;
+        };
         dispose: () => void;
     };
     captureFrame: typeof captureFrame;
 }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     error: (error: Error) => void;
-    ready: (quality: "thumbnail" | "screen" | "full") => void;
+    ready: (quality: "full" | "thumbnail" | "screen") => void;
     originalState: (status: OriginalStatus, reason: string) => void;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
     initialImage: () => InitialImage;
@@ -122,7 +138,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__V
     controlsTarget: string;
 }>>> & {
     onError?: ((error: Error) => any) | undefined;
-    onReady?: ((quality: "thumbnail" | "screen" | "full") => any) | undefined;
+    onReady?: ((quality: "full" | "thumbnail" | "screen") => any) | undefined;
     onOriginalState?: ((status: OriginalStatus, reason: string) => any) | undefined;
 }, {
     active: boolean;