@lazycatcloud/vue-media-preview 0.0.0-stage → 0.1.0-preview.34

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LazycatCloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# Vue Media Preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向懒猫相册的 Vue 3 媒体预览组件库。当前测试版包含日期时间线 Demo，以及卡片展开、Canvas 图片预览、跟手翻页、缩放平移和收回卡片的完整链路。
+
+## 直接体验
+
+```bash
+pnpm install
+pnpm dev
+```
+
+- 移动端效果：<http://localhost:2391/?view=mobile>
+- 万张图库场景：<http://localhost:2391/?view=mobile&count=10000>，在“我的”中定位第 5000 张。
+- 桌面端效果：<http://localhost:2391/?view=desktop>
+- 默认入口根据屏幕宽度和 UA 选择界面。
+- 手机连接同一局域网后，使用启动输出中的 Network 地址。
+- 点击“添加”可用自己的照片或视频测试；文件只通过浏览器 Blob URL 使用，不上传服务端，刷新后清除。视频自动提取首帧作为卡片封面。
+
+Demo 内置 48 个日期分组条目，复用 16 份图片、视频和实况素材。所有演示资源已放在 `demo/public/media/`，打开时不依赖外网图片服务。
+
+## 已包含的交互
+
+- **容器展开 / 共享元素转场**：图片从卡片的位置、裁切和圆角连续展开到完整预览；关闭时收回当前图片对应的卡片。
+- **Canvas 图片**：当前画面优先，再预取邻页；下载可取消并有并发、流量和像素保护，原图状态以真实解码结果为准。
+- **三页翻页轨道**：当前项及相邻两项，拖动跟手，松手根据距离和速度翻页或回弹，首尾有阻尼。
+- **海量列表**：日期分组虚拟时间线、分页事件、按 ID 定位收回；列表追加/重排保留当前媒体，删除当前项切到邻项。
+- **手势**：单击工具栏、双击缩放、双指缩放、放大后平移、越过水平边缘切页并同步缩回 1 倍、适配比例下拉关闭；图片和内联视频均支持缩放。
+- **桌面操作**：左右方向键、Escape、`+` / `-` / `0`；Ctrl / Command + 滚轮缩放，放大后普通滚轮平移。
+- **媒体**：图片 Canvas；视频使用原生 video 与自定义相册控制层，包含居中播放、播放/暂停、时间与缓冲进度、拖动定位、重播、声音开关和全屏；实况 Canvas 封面与视频切换。离开当前项暂停视频，退出释放组件资源。
+- **外壳**：移动端与桌面 Demo、工具栏插槽、收藏状态、详情、图片导入、失败重试、预览键盘操作和减少动态效果设置。
+
+## 验证与构建
+
+```bash
+pnpm format:check
+pnpm test
+pnpm type-check
+pnpm build
+pnpm preview
+```
+
+`pnpm preview` 在 2392 端口运行 `demo/dist` 的生产构建。
+
+```bash
+pnpm pack --pack-destination .delivery
+```
+
+生成的组件包包含 ESM、CommonJS、类型声明和 CSS。相册可通过本地 tgz 安装。
+
+## 接入
+
+安装当前预览版：
+
+```bash
+pnpm add @lazycatcloud/vue-media-preview@next vue
+```
+
+```ts
+import { MediaPreview } from '@lazycatcloud/vue-media-preview'
+import '@lazycatcloud/vue-media-preview/style.css'
+import type { PreviewMedia, PreviewAnchor } from '@lazycatcloud/vue-media-preview'
+```
+
+`MediaPreview` 负责完整预览会话，`PreviewStage` 提供单媒体缩放、平移、旋转能力。转场定位、业务动作和资源地址由接入方提供。
+
+详见 [接入与架构](docs/vue-media-preview.md) 和 [测试说明](docs/testing.md)。
+
+大原图通过独立适屏资源预览；默认不直接解码超过 32MiB 或 2400 万像素的原图，未实现瓦片式超大图。真实相册业务与特殊格式边界见接入文档。
+
+## npm 发布
+
+沿用 `vue-router-stack` 的 Makefile 发布入口，默认发布到 npm 官方源。先安装依赖并检查发布内容：
+
+```bash
+pnpm install --frozen-lockfile
+make npm-publish-dry-run
+```
+
+预演会执行类型检查、测试、库与 Demo 构建，并显示包内容，不上传包、不修改版本。
+发布包包含 `dist/`、`docs/`、README、MIT LICENSE 和包元数据。
+
+登录有 `@lazycatcloud` 发布权限的 npm 账号后发布当前版本：
+
+```bash
+npm login --registry https://registry.npmjs.org/
+make npm-publish
+```
+
+当前 `0.1.0-preview.*` 版本默认使用 `next` 标签；Makefile 对正式版本默认使用 `latest`。
+直接运行 `npm publish` 也会先检查、测试和构建，包配置默认标签为 `next`，正式发布时需显式指定 `--tag latest`。
+
+后续递增预览版本并发布：
+
+```bash
+make npm-release-preview
+```
+
+首次转为正式版可执行 `make npm-release VERSION=0.1.0 NPM_TAG=latest`；
+后续正式版本使用 `make npm-release-patch`、`make npm-release-minor` 或 `make npm-release-major`。
+版本更新默认不创建 Git 提交或标签；发布成功后手动提交版本变更。
+需要验证码时附加 `NPM_OTP=123456`，可通过 `NPM_REGISTRY`、`NPM_ACCESS`、`NPM_TAG` 覆盖发布目标。
+这些参数同样适用于预演命令；账号凭据通过 npm 登录管理，不写入仓库。
+
+## 代码约定
+
+TypeScript、Vue 模板、CSS 和测试统一采用 2 空格缩进、双引号和无分号风格，由 `.prettierrc.json` 与 `.editorconfig` 固定。运行 `pnpm format` 整理格式，`pnpm format:check` 检查；生成产物、交付包和复制的图标/媒体资源不参与格式化。
+
+资源模块位于 `src/core/resources/`：`imageLimits.ts` 集中固定预算，`imagePolicy.ts` 定义可配置策略和清晰度协议，`imageRequest.ts` 生成请求计划，`imageStore.ts` 管理队列和缓存，`usePreviewResources.ts` 管理当前页原图状态。渲染组件负责资源生命周期与绘制；预览会话保留转场、手势与界面编排。多语句模板事件使用具名处理函数，避免无分号格式下产生解析歧义。

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

@@ -0,0 +1,171 @@
+import type { VideoSourceLoader } from "../core/video/useVideoSource";
+import type { ImagePolicy, ImageSourceResolver, OriginalStatus } from "../core/resources/imagePolicy";
+import type { LivePhotoStatus, PreviewAnchor, PreviewMedia, PreviewPhase } from "../core/types";
+type __VLS_Props = {
+    items: PreviewMedia[];
+    mobile?: boolean;
+    teleportDisabled?: boolean;
+    keyboardEnabled?: boolean;
+    gesturesEnabled?: boolean;
+    persistentChrome?: boolean;
+    videoLoader?: VideoSourceLoader;
+    resourcePolicy?: ImagePolicy;
+    resolveImageSource?: ImageSourceResolver;
+    hasMore?: boolean;
+    appearance?: "dark" | "album";
+    closeDuration?: number;
+    transitionDuration?: number;
+    resolveAnchor?: (media: PreviewMedia) => PreviewAnchor | Promise<PreviewAnchor>;
+};
+/** Synchronize a host-owned window or jump directly from its filmstrip. */
+declare function goTo(index: number): void;
+declare function open(index?: number): Promise<void>;
+declare function close(): Promise<void>;
+declare function toggleFullscreen(): Promise<void>;
+declare var __VLS_24: {
+    media: PreviewMedia;
+    index: number;
+    total: number;
+    scale: number;
+    controls: {
+        close: typeof close;
+        setChromeVisible: (visible: boolean) => void;
+        goTo: typeof goTo;
+        previous: () => void;
+        next: () => void;
+        rotate: (delta?: number) => void;
+        reset: () => void;
+        zoomIn: () => void;
+        zoomOut: () => void;
+        original: () => void;
+        fullscreen: typeof toggleFullscreen;
+        togglePlayback: () => void;
+        toggleLive: () => void;
+        toggleDetail: () => void;
+    };
+    originalStatus: OriginalStatus;
+    originalReason: string;
+    livePlaying: boolean;
+    liveStatus: LivePhotoStatus;
+};
+type __VLS_Slots = {} & {
+    toolbar?: (props: typeof __VLS_24) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
+    mobile: boolean;
+    teleportDisabled: boolean;
+    keyboardEnabled: boolean;
+    gesturesEnabled: boolean;
+    persistentChrome: boolean;
+    videoLoader: VideoSourceLoader;
+    resourcePolicy: () => ImagePolicy;
+    resolveImageSource: ImageSourceResolver;
+    hasMore: boolean;
+    appearance: string;
+    closeDuration: number;
+    transitionDuration: number;
+    resolveAnchor: () => {
+        kind: "unavailable";
+    };
+}>, {
+    currentIndex: import("vue").Ref<number>;
+    phase: import("vue").Ref<PreviewPhase>;
+    element: import("vue").Ref<HTMLElement | undefined>;
+    mediaElement: () => HTMLImageElement | HTMLVideoElement | undefined;
+    canvasElement: () => HTMLCanvasElement;
+    close: typeof close;
+    setChromeVisible: (visible: boolean) => void;
+    goTo: typeof goTo;
+    previous: () => void;
+    next: () => void;
+    rotate: (delta?: number) => void;
+    reset: () => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    original: () => void;
+    fullscreen: typeof toggleFullscreen;
+    togglePlayback: () => void;
+    toggleLive: () => void;
+    toggleDetail: () => void;
+    open: typeof open;
+}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    error: (error: Error, media: PreviewMedia) => void;
+    open: (index: number) => void;
+    closing: () => void;
+    change: (index: number) => void;
+    close: () => void;
+    ready: (index: number, quality: "thumbnail" | "screen" | "full") => void;
+    originalState: (media: PreviewMedia, status: OriginalStatus, reason: string) => void;
+    opened: (index: number) => void;
+    loadMore: (index: number) => void;
+    phaseChange: (phase: PreviewPhase) => void;
+    chromeChange: (visible: boolean) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
+    mobile: boolean;
+    teleportDisabled: boolean;
+    keyboardEnabled: boolean;
+    gesturesEnabled: boolean;
+    persistentChrome: boolean;
+    videoLoader: VideoSourceLoader;
+    resourcePolicy: () => ImagePolicy;
+    resolveImageSource: ImageSourceResolver;
+    hasMore: boolean;
+    appearance: string;
+    closeDuration: number;
+    transitionDuration: number;
+    resolveAnchor: () => {
+        kind: "unavailable";
+    };
+}>>> & {
+    onError?: ((error: Error, media: PreviewMedia) => any) | undefined;
+    onReady?: ((index: number, quality: "thumbnail" | "screen" | "full") => any) | undefined;
+    onOriginalState?: ((media: PreviewMedia, status: OriginalStatus, reason: string) => any) | undefined;
+    onChange?: ((index: number) => any) | undefined;
+    onClose?: (() => any) | undefined;
+    onOpen?: ((index: number) => any) | undefined;
+    onClosing?: (() => any) | undefined;
+    onOpened?: ((index: number) => any) | undefined;
+    onLoadMore?: ((index: number) => any) | undefined;
+    onPhaseChange?: ((phase: PreviewPhase) => any) | undefined;
+    onChromeChange?: ((visible: boolean) => any) | undefined;
+}, {
+    resourcePolicy: ImagePolicy;
+    videoLoader: VideoSourceLoader;
+    mobile: boolean;
+    teleportDisabled: boolean;
+    keyboardEnabled: boolean;
+    gesturesEnabled: boolean;
+    persistentChrome: boolean;
+    resolveImageSource: ImageSourceResolver;
+    hasMore: boolean;
+    appearance: "dark" | "album";
+    closeDuration: number;
+    transitionDuration: number;
+    resolveAnchor: (media: PreviewMedia) => PreviewAnchor | Promise<PreviewAnchor>;
+}, {}>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<Required<T>[K]>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_PrettifyLocal<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

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

@@ -0,0 +1,147 @@
+import type { VideoSourceLoader } from "../core/video/useVideoSource";
+import type { ImagePolicy, ImageQuality, ImageSourceResolver, OriginalStatus } from "../core/resources/imagePolicy";
+import type { InitialImage } from "../core/resources/initialImage";
+import type { LivePhotoStatus, PreviewMedia } from "../core/types";
+type __VLS_Props = {
+    media: PreviewMedia;
+    videoLoader?: VideoSourceLoader;
+    livePlaying?: boolean;
+    active?: boolean;
+    requestVersion?: number;
+    loadEnabled?: boolean;
+    resourcePolicy?: ImagePolicy;
+    resolveSource?: ImageSourceResolver;
+    inactiveResetDuration?: number;
+    disabled?: boolean;
+    externalGestures?: boolean;
+    controlsVisible?: boolean;
+    teleportControls?: boolean;
+    controlsTarget?: string;
+    rendering?: boolean;
+    paging?: boolean;
+    initialImage?: InitialImage;
+    quality?: ImageQuality;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
+    videoLoader: VideoSourceLoader;
+    livePlaying: boolean;
+    active: boolean;
+    inactiveResetDuration: number;
+    loadEnabled: boolean;
+    requestVersion: number;
+    resourcePolicy: () => ImagePolicy;
+    resolveSource: ImageSourceResolver;
+    disabled: boolean;
+    externalGestures: boolean;
+    controlsVisible: boolean;
+    teleportControls: boolean;
+    controlsTarget: string;
+    quality: string;
+    initialImage: () => InitialImage;
+    rendering: boolean;
+    paging: boolean;
+}>, {
+    onPointerDown: (event: PointerEvent, origin?: DOMRect) => boolean;
+    onPointerMove: (event: PointerEvent) => void;
+    onPointerUp: (event: PointerEvent) => void;
+    onPointerCancel: (event: PointerEvent) => void;
+    onWheel: (event: WheelEvent) => void;
+    readiness: import("vue").Ref<"loading" | "ready">;
+    core: import("../index.ts").PreviewViewportCore;
+    rotateBy: (delta?: number) => void;
+    resetTransform: (duration?: number) => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    togglePlayback: () => void;
+    toggleFullscreen: () => Promise<void>;
+    captureFrame: () => {
+        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;
+    originalState: (status: OriginalStatus, reason: string) => void;
+    liveState: (status: LivePhotoStatus) => void;
+    liveEnded: () => void;
+    tap: () => void;
+    doubleTap: () => void;
+    scale: (level: number) => void;
+    swipeDownProgress: (progress: number) => void;
+    previous: () => void;
+    next: () => void;
+    pageDrag: (offset: number) => void;
+    pageRelease: (offset: number, velocity: number) => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_WithDefaults<__VLS_TypePropsToOption<__VLS_Props>, {
+    videoLoader: VideoSourceLoader;
+    livePlaying: boolean;
+    active: boolean;
+    inactiveResetDuration: number;
+    loadEnabled: boolean;
+    requestVersion: number;
+    resourcePolicy: () => ImagePolicy;
+    resolveSource: ImageSourceResolver;
+    disabled: boolean;
+    externalGestures: boolean;
+    controlsVisible: boolean;
+    teleportControls: boolean;
+    controlsTarget: string;
+    quality: string;
+    initialImage: () => InitialImage;
+    rendering: boolean;
+    paging: boolean;
+}>>> & {
+    onError?: ((error: Error) => any) | undefined;
+    onReady?: ((quality: "thumbnail" | "screen" | "full") => any) | undefined;
+    onOriginalState?: ((status: OriginalStatus, reason: string) => any) | undefined;
+    onLiveState?: ((status: LivePhotoStatus) => any) | undefined;
+    onLiveEnded?: (() => any) | undefined;
+    onClose?: (() => any) | undefined;
+    onTap?: (() => any) | undefined;
+    onDoubleTap?: (() => any) | undefined;
+    onScale?: ((level: number) => any) | undefined;
+    onSwipeDownProgress?: ((progress: number) => any) | undefined;
+    onPrevious?: (() => any) | undefined;
+    onNext?: (() => any) | undefined;
+    onPageDrag?: ((offset: number) => any) | undefined;
+    onPageRelease?: ((offset: number, velocity: number) => any) | undefined;
+}, {
+    active: boolean;
+    quality: ImageQuality;
+    rendering: boolean;
+    requestVersion: number;
+    loadEnabled: boolean;
+    resourcePolicy: ImagePolicy;
+    resolveSource: ImageSourceResolver;
+    initialImage: InitialImage;
+    disabled: boolean;
+    videoLoader: VideoSourceLoader;
+    controlsVisible: boolean;
+    teleportControls: boolean;
+    controlsTarget: string;
+    livePlaying: boolean;
+    inactiveResetDuration: number;
+    externalGestures: boolean;
+    paging: boolean;
+}, {}>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<Required<T>[K]>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};
+type __VLS_WithDefaults<P, D> = {
+    [K in keyof Pick<P, keyof P>]: K extends keyof D ? __VLS_PrettifyLocal<P[K] & {
+        default: D[K];
+    }> : P[K];
+};
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

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

@@ -0,0 +1,42 @@
+import type { TimelineGroup } from "../core/timeline/layout";
+import type { PreviewAnchor } from "../core/types";
+declare const __VLS_export: <T extends {
+    id: string;
+}>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        groups: TimelineGroup<T>[];
+        scrollElement: () => HTMLElement;
+        mobile?: boolean;
+        hasMore?: boolean;
+    } & {
+        onLoadMore?: (() => any) | undefined;
+        onDate?: ((key: string) => any) | undefined;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: import("vue").ShallowUnwrapRef<{
+        resolveAnchor: (id: string) => Promise<PreviewAnchor>;
+        rendered: import("vue").ComputedRef<number>;
+        total: import("vue").ComputedRef<number>;
+    }>) => void;
+    attrs: any;
+    slots: {
+        item(props: {
+            item: T;
+        }): unknown;
+        header(props: {
+            group: TimelineGroup<T>;
+            index: number;
+        }): unknown;
+    };
+    emit: ((evt: "loadMore") => void) & ((evt: "date", key: string) => void);
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/components/video/VideoControls.vue.d.ts

@@ -0,0 +1,21 @@
+import type { useVideoPlayback } from "../../core/video/useVideoPlayback";
+type __VLS_Props = {
+    playback: ReturnType<typeof useVideoPlayback>;
+    fullscreen: boolean;
+    canFullscreen: boolean;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_TypePropsToOption<__VLS_Props>, unknown, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    fullscreen: () => void;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToOption<__VLS_Props>>> & {
+    onFullscreen?: (() => any) | undefined;
+}, {}, {}>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<Required<T>[K]>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};

package/dist/components/video/VideoIcon.vue.d.ts

@@ -0,0 +1,14 @@
+type __VLS_Props = {
+    name: "play" | "pause" | "replay" | "fullscreen" | "exit" | "volume" | "muted";
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_TypePropsToOption<__VLS_Props>, unknown, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToOption<__VLS_Props>>>, {}, {}>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_TypePropsToOption<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<Required<T>[K]>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};

package/dist/core/errors.d.ts

@@ -0,0 +1 @@
+export declare function asError(error: unknown): Error;

package/dist/core/gestures/edgePaging.d.ts

@@ -0,0 +1,5 @@
+/** Consume movement inside the zoomed image; only its horizontal overflow moves pages. */
+export declare function splitEdgePan(x: number, maxX: number, paging: boolean): {
+    offsetX: number;
+    pageOffset: number;
+};

package/dist/core/gestures/pointerGesture.d.ts

@@ -0,0 +1,5 @@
+import type { PreviewPoint } from "../types";
+export type GestureMode = "idle" | "pending" | "hold" | "pan" | "page" | "dismiss" | "pinch";
+export declare function distance(a: PreviewPoint, b: PreviewPoint): number;
+export declare function midpoint(a: PreviewPoint, b: PreviewPoint): PreviewPoint;
+export declare function chooseGesture(dx: number, dy: number, level: number): GestureMode;

package/dist/core/gestures/pressHold.d.ts

@@ -0,0 +1,5 @@
+/** Hold timing is independent of paging, zooming and media playback. */
+export declare function createPressHold(onStart: () => void, onEnd: () => void, delay?: number): {
+    arm: () => void;
+    cancel: () => void;
+};

package/dist/core/gestures/wheelZoom.d.ts

@@ -0,0 +1,2 @@
+/** Match the album's physical Ctrl/Meta + wheel steps without slowing smooth trackpad pinches. */
+export declare function wheelZoomFactor(event: Pick<WheelEvent, "deltaY" | "deltaMode">, keyboardZoom: boolean): number;

package/dist/core/math.d.ts

@@ -0,0 +1,11 @@
+import type { PreviewDirection, PreviewPoint, PreviewRotation, PreviewSize } from "./types";
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function round(value: number, fractionDigits?: number): number;
+export declare function containScale(source: PreviewSize, viewport: PreviewSize): number;
+export declare function normalizeRotation(rotation: number): PreviewRotation;
+export declare function rotateSize(size: PreviewSize, rotation: PreviewRotation): PreviewSize;
+export declare function getDistance(touches: TouchList): number;
+export declare function getCenter(touches: TouchList): PreviewPoint;
+export declare function getDirection(offsetX: number, offsetY: number): PreviewDirection;
+export declare function getTransform(offsetX: number, offsetY: number, scale: number): string;
+export declare function easeOutCubic(progress: number): number;

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

@@ -0,0 +1,11 @@
+/** Resource budgets shared by transport, caching and Canvas renderers. */
+export declare const imageLimits: {
+    readonly maxDecodedPixels: 24000000;
+    readonly maxCanvasPixels: 6000000;
+    readonly maxDevicePixelRatio: 2.5;
+    readonly maxOriginalBytes: number;
+    readonly maxPreviewBytes: number;
+    readonly cacheBytes: number;
+    readonly cacheEntries: 24;
+    readonly concurrency: 3;
+};

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

@@ -0,0 +1,14 @@
+import type { PreviewMedia, PreviewSize } from "../types";
+export declare const imageQualities: readonly ["thumbnail", "screen", "full"];
+export type ImageQuality = (typeof imageQualities)[number];
+export type OriginalStatus = "idle" | "loading" | "ready" | "error" | "blocked";
+export interface ImagePolicy {
+    maxOriginalPixels: number;
+    maxOriginalBytes: number;
+    maxPreviewBytes: number;
+}
+export declare const defaultImagePolicy: ImagePolicy;
+export type ImageSourceResolver = (media: PreviewMedia, quality: ImageQuality, targetWidth: number) => string;
+export declare const defaultImageSource: ImageSourceResolver;
+export declare function originalAllowed(media: PreviewMedia, policy: ImagePolicy): boolean;
+export declare function smartZoom(media: PreviewSize, viewport: PreviewSize): number;

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

@@ -0,0 +1,15 @@
+import type { ImagePolicy, ImageQuality, ImageSourceResolver, OriginalStatus } from "./imagePolicy";
+import type { PreviewMedia } from "../types";
+interface ImageSource {
+    url: string;
+    quality: ImageQuality;
+    rank: number;
+}
+interface ImageRequest {
+    sources: ImageSource[];
+    originalStatus: OriginalStatus;
+    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 {};

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

@@ -0,0 +1,30 @@
+import type { ImageLoader } from "./imageTransport";
+export interface ImageLease {
+    ready: Promise<HTMLImageElement>;
+    release: () => void;
+}
+export interface ImageRequestOptions {
+    priority?: number;
+    maxBytes?: number;
+}
+/** Shared ownership, bounded fetch/decode concurrency and cancellation of unowned requests. */
+export declare class ImageStore {
+    private budget;
+    private concurrency;
+    private loader;
+    private entries;
+    private active;
+    private cancelled;
+    constructor(budget?: number, concurrency?: number, loader?: ImageLoader);
+    get stats(): {
+        active: number;
+        queued: number;
+        entries: number;
+        bytes: number;
+        cancelled: number;
+    };
+    acquire(url: string, options?: ImageRequestOptions): ImageLease;
+    private pump;
+    private trim;
+}
+export declare const previewImageStore: ImageStore;

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

@@ -0,0 +1,9 @@
+export declare class ImageLimitError extends Error {
+    constructor(message: string);
+}
+export interface ImageLoadOptions {
+    signal: AbortSignal;
+    readonly maxBytes: number;
+}
+export type ImageLoader = (url: string, options: ImageLoadOptions) => Promise<HTMLImageElement>;
+export declare const loadImage: ImageLoader;