@jini-ai/ui 0.1.0

package/dist/features/version-manager/react/hooks/useVersionManager.js

@@ -0,0 +1,287 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useI18n } from '../../../i18n/index.js';
+import { DEFAULT_VIEWPORT_PRESETS } from '../../../viewer-shell/index.js';
+import { PREVIEW_LOAD_FALLBACK_MS, SEARCH_VISIBLE_THRESHOLD, } from '../../constants.js';
+import { defaultVersionManagerDependencies } from '../../dependencies.js';
+import { buildVersionIndex, contentMatchesSelection, filterVersionsBySearch, formatVersionDateTime, isRestoreDisabled, restoredFromVersion, resolveSelectedVersion, shouldShowVersionSearch, sortVersionsDescending, versionSourceLabel, } from '../../rules.js';
+/**
+ * Owns the whole version-manager state machine: list fetch, selection,
+ * content cache/prefetch, search, restore, and viewport choice. Kept as one
+ * cohesive hook per this package's Phase 6 "one natural owning cluster"
+ * discipline (matching `features/connectors/`'s `useConnectorAuthorization`
+ * precedent) — the source's own version, list, and preview state are all
+ * read/written by each other's effects and don't split cleanly.
+ */
+export function useVersionManager(dependencies, options) {
+    const { fileRef, currentContent, onRestored, onRestoredCleanly, viewportPresets = DEFAULT_VIEWPORT_PRESETS } = options;
+    const port = dependencies.versions;
+    const { locale, t } = useI18n();
+    // Latest-ref indirection so the fetch callbacks below don't need `t` in
+    // their dependency arrays (see this package's documented infinite-loop
+    // gotcha for hooks that call useT()/useI18n() from an effect).
+    const tRef = useRef(t);
+    useEffect(() => {
+        tRef.current = t;
+    }, [t]);
+    const [versions, setVersions] = useState([]);
+    const [selectedId, setSelectedId] = useState(null);
+    const [selectedContent, setSelectedContent] = useState(currentContent);
+    const [selectedContentVersionId, setSelectedContentVersionId] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [loadingContent, setLoadingContent] = useState(false);
+    const [error, setError] = useState(null);
+    const [restoring, setRestoring] = useState(false);
+    const [search, setSearch] = useState('');
+    const [viewport, setViewport] = useState(viewportPresets[0]?.id ?? 'desktop');
+    const [loadedPreviewDocument, setLoadedPreviewDocument] = useState(null);
+    const contentCacheRef = useRef(new Map());
+    const inFlightRef = useRef(new Map());
+    // Set right before a restore-warning reload changes `selectedId` (which
+    // re-triggers the content-load effect below); consumed once by that
+    // effect to skip its normal `setError(null)` so the just-set warning
+    // message survives the version switch instead of being immediately
+    // clobbered. See the `restore` warning branch.
+    const preserveErrorOnNextSelectionRef = useRef(false);
+    const versionById = useMemo(() => buildVersionIndex(versions), [versions]);
+    const selectedVersion = resolveSelectedVersion(versions, versionById, selectedId);
+    const showSearch = shouldShowVersionSearch(versions.length, SEARCH_VISIBLE_THRESHOLD);
+    const describeVersion = useCallback((version) => {
+        const from = restoredFromVersion(version, versionById);
+        return [
+            `v${version.version}`,
+            `version ${version.version}`,
+            version.prompt ?? '',
+            version.label ?? '',
+            tRef.current(versionSourceLabel(version.source)),
+            formatVersionDateTime(version.createdAt, locale),
+            from ? `v${from.version}` : '',
+        ]
+            .join(' ')
+            .toLowerCase();
+    }, [versionById, locale]);
+    const visibleVersions = useMemo(() => (showSearch ? filterVersionsBySearch(versions, search, describeVersion) : versions), [showSearch, versions, search, describeVersion]);
+    const selectedContentMatchesVersion = contentMatchesSelection(selectedId, selectedContentVersionId, selectedContent);
+    const restoreDisabled = isRestoreDisabled({
+        selectedVersion,
+        restoring,
+        loadingContent,
+        selectedContentMatchesVersion,
+    });
+    const previewDocument = useMemo(() => (selectedContent ? port.resolvePreviewDocument(fileRef, selectedContent) : ''), [port, fileRef, selectedContent]);
+    const frameReady = loadedPreviewDocument === previewDocument;
+    // Primes the content cache for one version at most once, deduping
+    // concurrent callers (hover-prefetch racing the click that selects it).
+    const primeVersionContent = useCallback((versionId) => {
+        if (contentCacheRef.current.has(versionId))
+            return Promise.resolve();
+        const pending = inFlightRef.current.get(versionId);
+        if (pending)
+            return pending;
+        const request = port
+            .fetchVersionContent(fileRef, versionId)
+            .then((result) => {
+            if (result != null)
+                contentCacheRef.current.set(versionId, result);
+        })
+            .catch(() => { })
+            .finally(() => {
+            inFlightRef.current.delete(versionId);
+        });
+        inFlightRef.current.set(versionId, request);
+        return request;
+    }, [port, fileRef]);
+    const loadVersions = useCallback(async (preferredId) => {
+        setLoading(true);
+        setError(null);
+        const result = await port.listVersions(fileRef);
+        if (!result) {
+            setError(tRef.current('Couldn’t load version history.'));
+            setLoading(false);
+            return;
+        }
+        const nextVersions = sortVersionsDescending(result);
+        setVersions(nextVersions);
+        const currentVersion = nextVersions.find((version) => version.current);
+        if (currentVersion && currentContent != null && !contentCacheRef.current.has(currentVersion.id)) {
+            contentCacheRef.current.set(currentVersion.id, currentContent);
+        }
+        const nextSelected = (preferredId ? nextVersions.find((version) => version.id === preferredId) : null) ??
+            currentVersion ??
+            nextVersions[0] ??
+            null;
+        setSelectedId(nextSelected?.id ?? null);
+        setLoading(false);
+    }, [port, fileRef, currentContent]);
+    // Re-fetches whenever `loadVersions`'s own dependencies change — including
+    // `currentContent` — matching the source exactly (a fresh `currentContent`
+    // re-lists so it can be cache-seeded as the new `current` version's body).
+    useEffect(() => {
+        void loadVersions();
+    }, [loadVersions]);
+    useEffect(() => {
+        if (!selectedId) {
+            setSelectedContent(null);
+            setSelectedContentVersionId(null);
+            return;
+        }
+        const cached = contentCacheRef.current.get(selectedId);
+        if (cached !== undefined) {
+            setSelectedContent(cached);
+            setSelectedContentVersionId(selectedId);
+            setLoadingContent(false);
+            if (preserveErrorOnNextSelectionRef.current) {
+                preserveErrorOnNextSelectionRef.current = false;
+            }
+            else {
+                setError(null);
+            }
+            return;
+        }
+        // Cache miss: keep the previous preview mounted (don't clear
+        // `selectedContent`) so switching versions never blanks to empty while
+        // the loading overlay covers it.
+        //
+        // No `preserveErrorOnNextSelectionRef` check here (unlike the cache-hit
+        // branch above): the only caller that sets that flag (`restore`'s
+        // warning branch) always seeds the cache for the version it switches
+        // to first, so that switch can only ever land in the cache-HIT branch
+        // above — this branch genuinely cannot run with the flag set. A real
+        // cache-miss always means a genuinely new fetch starting, which should
+        // unconditionally clear a stale error.
+        let cancelled = false;
+        setLoadingContent(true);
+        setError(null);
+        void primeVersionContent(selectedId).then(() => {
+            if (cancelled)
+                return;
+            const next = contentCacheRef.current.get(selectedId);
+            if (next === undefined) {
+                setSelectedContent(null);
+                setSelectedContentVersionId(null);
+                setError(tRef.current('Couldn’t load this version’s preview.'));
+            }
+            else {
+                setSelectedContent(next);
+                setSelectedContentVersionId(selectedId);
+            }
+            setLoadingContent(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [primeVersionContent, selectedId]);
+    // Safety net: clear a stuck loading overlay if the iframe's `load` event
+    // is ever missed.
+    useEffect(() => {
+        if (!previewDocument || loadedPreviewDocument === previewDocument)
+            return;
+        const fallback = setTimeout(() => setLoadedPreviewDocument(previewDocument), PREVIEW_LOAD_FALLBACK_MS);
+        return () => clearTimeout(fallback);
+    }, [previewDocument, loadedPreviewDocument]);
+    const restore = useCallback(async () => {
+        if (isRestoreDisabled({ selectedVersion, restoring, loadingContent, selectedContentMatchesVersion }) ||
+            !selectedVersion ||
+            !selectedContent) {
+            return;
+        }
+        setRestoring(true);
+        setError(null);
+        let handledRestore = false;
+        try {
+            const result = await port.restoreVersion(fileRef, selectedVersion);
+            if (!result) {
+                setError(tRef.current('Restore failed.'));
+                return;
+            }
+            const restoredVersion = result.version ?? selectedVersion;
+            await onRestored(selectedContent, restoredVersion);
+            if (result.warning) {
+                // Seed the cache with the content we already have in hand — it's
+                // exactly what was just restored — so the list reload below
+                // selects the new version as a cache HIT. Without this, the
+                // content-load effect's own fetch-start `setError(null)` (for a
+                // legitimate reason: clearing a stale error when starting a new
+                // load) would race with and clobber the warning message set right
+                // below, once React flushes that effect after this restore
+                // completes. Seeding also avoids a pointless refetch of content
+                // this hook already has.
+                contentCacheRef.current.set(restoredVersion.id, selectedContent);
+                preserveErrorOnNextSelectionRef.current = true;
+                await loadVersions(result.version?.id ?? selectedVersion.id);
+                setError(result.warning.message);
+                return;
+            }
+            handledRestore = true;
+            onRestoredCleanly?.();
+        }
+        finally {
+            if (!handledRestore)
+                setRestoring(false);
+        }
+    }, [
+        selectedVersion,
+        restoring,
+        loadingContent,
+        selectedContentMatchesVersion,
+        selectedContent,
+        port,
+        fileRef,
+        onRestored,
+        onRestoredCleanly,
+        loadVersions,
+    ]);
+    const openInNewTab = useMemo(() => {
+        if (!port.openPreviewInNewTab)
+            return null;
+        return () => {
+            if (loadingContent || !selectedContentMatchesVersion || !selectedContent || !selectedVersion)
+                return;
+            port.openPreviewInNewTab(fileRef, selectedContent, `${fileRef.name} · v${selectedVersion.version}`);
+        };
+    }, [port, fileRef, loadingContent, selectedContentMatchesVersion, selectedContent, selectedVersion]);
+    return {
+        versions,
+        visibleVersions,
+        versionById,
+        selectedVersion,
+        selectedId,
+        selectVersion: setSelectedId,
+        prefetchVersion: (id) => {
+            void primeVersionContent(id);
+        },
+        restoredFrom: (version) => restoredFromVersion(version, versionById),
+        loading,
+        loadingContent,
+        error,
+        search,
+        setSearch,
+        showSearch,
+        selectedContent,
+        previewDocument,
+        frameReady,
+        markFrameLoaded: setLoadedPreviewDocument,
+        restoring,
+        restoreDisabled,
+        restore,
+        openInNewTab,
+        viewportPresets,
+        viewport,
+        setViewport,
+        describeVersion,
+    };
+}
+/**
+ * Production wiring for `useVersionManager`: binds the module-level default
+ * dependencies singleton (a stateless fake port + the real stateless
+ * browser clipboard — see `dependencies.ts`'s `defaultVersionManagerDependencies`
+ * for why this must stay ONE shared instance rather than a fresh call per
+ * render: a fresh `dependencies.versions` identity every render would
+ * re-trigger `loadVersions`'s effect in a loop, the same reasoning
+ * `useWiredCopyToClipboard` in `features/viewer-shell/` documents for its
+ * own singleton). A real host supplies its own `VersionManagerDependencies`
+ * directly to `useVersionManager` instead of using this wirer.
+ */
+export function useWiredVersionManager(options, dependencies = defaultVersionManagerDependencies) {
+    return useVersionManager(dependencies, options);
+}
+//# sourceMappingURL=useVersionManager.js.map

package/dist/features/version-manager/react/hooks/useVersionManager.js.map

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

package/dist/features/version-manager/rules.d.ts

@@ -0,0 +1,76 @@
+import type { ViewportPreset } from '../viewer-shell/index.js';
+import type { PreviewCanvasSize, VersionRecord, VersionSource } from './types.js';
+/** Formats an epoch-millis timestamp for the version list/header, using the
+ *  host's locale. Falls back to the runtime default locale formatting if
+ *  the given locale tag is invalid — matches the source's own try/catch
+ *  fallback rather than throwing on a bad locale string. */
+export declare function formatVersionDateTime(value: number | undefined, locale: string): string;
+/** Plain-English label for a version's `source` — the caller wraps this in
+ *  `t()` at the call site (the English string is the translation key
+ *  convention this package uses; see `packages/ui/README.md`). */
+export declare function versionSourceLabel(source: VersionSource): string;
+/** CSS class suffix for a version's source badge. */
+export declare function versionSourceClassName(source: VersionSource): string;
+/** Newest-first order, matching the source's own list ordering. */
+export declare function sortVersionsDescending<TVersion extends VersionRecord>(versions: readonly TVersion[]): TVersion[];
+/** Builds an id → version lookup map, used for resolving `restoreFromVersionId`
+ *  references and for O(1) selection lookups. */
+export declare function buildVersionIndex<TVersion extends VersionRecord>(versions: readonly TVersion[]): Map<string, TVersion>;
+/** The version a given version was restored from, if any and if still
+ *  present in the current list. */
+export declare function restoredFromVersion<TVersion extends VersionRecord>(version: TVersion | null | undefined, versionById: ReadonlyMap<string, TVersion>): TVersion | null;
+/** Resolves the effective "selected" version: an explicit selection if one
+ *  is set and still present, else the version flagged `current`, else the
+ *  first (newest) version, else `null` for an empty list. Matches the
+ *  source's own selection-fallback chain exactly. */
+export declare function resolveSelectedVersion<TVersion extends VersionRecord>(versions: readonly TVersion[], versionById: ReadonlyMap<string, TVersion>, selectedId: string | null): TVersion | null;
+/** Should the search box be shown at all — only once the list is long
+ *  enough to need filtering. */
+export declare function shouldShowVersionSearch(versionCount: number, threshold: number): boolean;
+/**
+ * Filters `versions` by a case-insensitive substring match against a
+ * caller-supplied per-version description string. Kept hook-free (no
+ * `useT()`/locale here) per this package's i18n convention — the caller
+ * builds `describe()` using its own `t()`/locale and the other pure
+ * helpers above (`versionSourceLabel`, `formatVersionDateTime`,
+ * `restoredFromVersion`), then this function only does the filtering.
+ */
+export declare function filterVersionsBySearch<TVersion extends VersionRecord>(versions: readonly TVersion[], search: string, describe: (version: TVersion) => string): TVersion[];
+export interface RestoreDisabledInput<TVersion extends VersionRecord> {
+    selectedVersion: TVersion | null;
+    restoring: boolean;
+    loadingContent: boolean;
+    selectedContentMatchesVersion: boolean;
+}
+/** Whether the restore action should be disabled — mirrors the source's
+ *  `restoreDisabled` derivation exactly (no restoring the version already
+ *  current, no restoring mid-fetch, no restoring stale/mismatched content). */
+export declare function isRestoreDisabled<TVersion extends VersionRecord>(input: RestoreDisabledInput<TVersion>): boolean;
+/** Whether the currently-loaded preview content actually corresponds to the
+ *  currently-selected version (guards against acting on stale content
+ *  during a version switch's in-flight fetch). */
+export declare function contentMatchesSelection(selectedId: string | null, selectedContentVersionId: string | null, selectedContent: string | null): boolean;
+/** Finds a viewport preset by id, falling back to the first preset in the
+ *  list (matches `ViewportSwitcher`/`ViewportToggleGroup`'s own fallback
+ *  behavior in `features/viewer-shell/`). */
+export declare function findViewportPreset(presets: readonly ViewportPreset[], id: string): ViewportPreset;
+/**
+ * How much a fixed-size viewport preset (tablet/mobile — `width`/`height`
+ * both non-null) must be scaled down to fit inside the measured canvas.
+ * A preset with `width === null` ("no fixed frame", e.g. "desktop") is
+ * never scaled by this function — it returns `previewScale` unchanged,
+ * generalizing the source's `viewport === 'desktop'` special case to any
+ * preset that opts out of fixed framing.
+ */
+export declare function effectivePreviewScale(preset: ViewportPreset, previewScale: number, canvasSize: PreviewCanvasSize | undefined, canvasPadding: number): number;
+/** CSS custom properties driving the fixed-size preview frame's dimensions
+ *  and scale. Returns an empty object for a "no fixed frame" preset (the
+ *  frame just fills its container at 100%, no custom properties needed). */
+export declare function previewViewportStyle(preset: ViewportPreset, effectiveScale: number, previewScale: number): Record<string, string | number>;
+/** Inline style for the scaled shell wrapping the preview iframe. A
+ *  "no fixed frame" preset scales the whole shell directly by
+ *  `previewScale`; a fixed-size preset instead sizes to the CSS custom
+ *  properties `previewViewportStyle` sets and scales by the *fitted*
+ *  `--preview-scale` variable, matching the source's two-mode behavior. */
+export declare function previewScaleShellStyle(preset: ViewportPreset, previewScale: number): Record<string, string>;
+//# sourceMappingURL=rules.d.ts.map

package/dist/features/version-manager/rules.d.ts.map

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

package/dist/features/version-manager/rules.js

@@ -0,0 +1,162 @@
+/** Formats an epoch-millis timestamp for the version list/header, using the
+ *  host's locale. Falls back to the runtime default locale formatting if
+ *  the given locale tag is invalid — matches the source's own try/catch
+ *  fallback rather than throwing on a bad locale string. */
+export function formatVersionDateTime(value, locale) {
+    const date = new Date(typeof value === 'number' && Number.isFinite(value) ? value : Date.now());
+    try {
+        return date.toLocaleString(locale, {
+            month: 'short',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+        });
+    }
+    catch {
+        return date.toLocaleString();
+    }
+}
+/** Plain-English label for a version's `source` — the caller wraps this in
+ *  `t()` at the call site (the English string is the translation key
+ *  convention this package uses; see `packages/ui/README.md`). */
+export function versionSourceLabel(source) {
+    if (source === 'manual')
+        return 'Manual';
+    if (source === 'restore')
+        return 'Restored';
+    return 'AI generated';
+}
+/** CSS class suffix for a version's source badge. */
+export function versionSourceClassName(source) {
+    if (source === 'manual')
+        return 'manual';
+    if (source === 'restore')
+        return 'restore';
+    return 'ai';
+}
+/** Newest-first order, matching the source's own list ordering. */
+export function sortVersionsDescending(versions) {
+    return [...versions].sort((a, b) => b.version - a.version);
+}
+/** Builds an id → version lookup map, used for resolving `restoreFromVersionId`
+ *  references and for O(1) selection lookups. */
+export function buildVersionIndex(versions) {
+    const map = new Map();
+    for (const version of versions)
+        map.set(version.id, version);
+    return map;
+}
+/** The version a given version was restored from, if any and if still
+ *  present in the current list. */
+export function restoredFromVersion(version, versionById) {
+    if (!version?.restoreFromVersionId)
+        return null;
+    return versionById.get(version.restoreFromVersionId) ?? null;
+}
+/** Resolves the effective "selected" version: an explicit selection if one
+ *  is set and still present, else the version flagged `current`, else the
+ *  first (newest) version, else `null` for an empty list. Matches the
+ *  source's own selection-fallback chain exactly. */
+export function resolveSelectedVersion(versions, versionById, selectedId) {
+    if (selectedId) {
+        const explicit = versionById.get(selectedId);
+        if (explicit)
+            return explicit;
+    }
+    return versions.find((version) => version.current) ?? versions[0] ?? null;
+}
+/** Should the search box be shown at all — only once the list is long
+ *  enough to need filtering. */
+export function shouldShowVersionSearch(versionCount, threshold) {
+    return versionCount > threshold;
+}
+/**
+ * Filters `versions` by a case-insensitive substring match against a
+ * caller-supplied per-version description string. Kept hook-free (no
+ * `useT()`/locale here) per this package's i18n convention — the caller
+ * builds `describe()` using its own `t()`/locale and the other pure
+ * helpers above (`versionSourceLabel`, `formatVersionDateTime`,
+ * `restoredFromVersion`), then this function only does the filtering.
+ */
+export function filterVersionsBySearch(versions, search, describe) {
+    const normalized = search.trim().toLowerCase();
+    if (!normalized)
+        return [...versions];
+    return versions.filter((version) => describe(version).toLowerCase().includes(normalized));
+}
+/** Whether the restore action should be disabled — mirrors the source's
+ *  `restoreDisabled` derivation exactly (no restoring the version already
+ *  current, no restoring mid-fetch, no restoring stale/mismatched content). */
+export function isRestoreDisabled(input) {
+    const { selectedVersion, restoring, loadingContent, selectedContentMatchesVersion } = input;
+    return (!selectedVersion ||
+        selectedVersion.current ||
+        restoring ||
+        loadingContent ||
+        !selectedContentMatchesVersion);
+}
+/** Whether the currently-loaded preview content actually corresponds to the
+ *  currently-selected version (guards against acting on stale content
+ *  during a version switch's in-flight fetch). */
+export function contentMatchesSelection(selectedId, selectedContentVersionId, selectedContent) {
+    return Boolean(selectedId && selectedContentVersionId === selectedId && selectedContent);
+}
+/** Finds a viewport preset by id, falling back to the first preset in the
+ *  list (matches `ViewportSwitcher`/`ViewportToggleGroup`'s own fallback
+ *  behavior in `features/viewer-shell/`). */
+export function findViewportPreset(presets, id) {
+    return presets.find((preset) => preset.id === id) ?? presets[0];
+}
+/**
+ * How much a fixed-size viewport preset (tablet/mobile — `width`/`height`
+ * both non-null) must be scaled down to fit inside the measured canvas.
+ * A preset with `width === null` ("no fixed frame", e.g. "desktop") is
+ * never scaled by this function — it returns `previewScale` unchanged,
+ * generalizing the source's `viewport === 'desktop'` special case to any
+ * preset that opts out of fixed framing.
+ */
+export function effectivePreviewScale(preset, previewScale, canvasSize, canvasPadding) {
+    if (!preset.width || !preset.height)
+        return previewScale;
+    if (!canvasSize || !canvasSize.width || !canvasSize.height)
+        return previewScale;
+    const availableWidth = Math.max(1, canvasSize.width - canvasPadding);
+    const availableHeight = Math.max(1, canvasSize.height - canvasPadding);
+    const fitScale = Math.min(1, availableWidth / preset.width, availableHeight / preset.height);
+    return Math.min(previewScale, fitScale);
+}
+/** CSS custom properties driving the fixed-size preview frame's dimensions
+ *  and scale. Returns an empty object for a "no fixed frame" preset (the
+ *  frame just fills its container at 100%, no custom properties needed). */
+export function previewViewportStyle(preset, effectiveScale, previewScale) {
+    if (!preset.width)
+        return {};
+    return {
+        '--preview-viewport-width': `${preset.width}px`,
+        '--preview-viewport-height': `${preset.height}px`,
+        '--preview-scale': effectiveScale,
+        '--preview-user-scale': previewScale,
+    };
+}
+/** Inline style for the scaled shell wrapping the preview iframe. A
+ *  "no fixed frame" preset scales the whole shell directly by
+ *  `previewScale`; a fixed-size preset instead sizes to the CSS custom
+ *  properties `previewViewportStyle` sets and scales by the *fitted*
+ *  `--preview-scale` variable, matching the source's two-mode behavior. */
+export function previewScaleShellStyle(preset, previewScale) {
+    if (!preset.width) {
+        return {
+            width: `${100 / previewScale}%`,
+            height: `${100 / previewScale}%`,
+            transform: `scale(${previewScale})`,
+            transformOrigin: '0 0',
+        };
+    }
+    return {
+        width: 'var(--preview-viewport-width)',
+        height: 'var(--preview-viewport-height)',
+        transform: 'scale(var(--preview-scale, 1))',
+        transformOrigin: '0 0',
+    };
+}
+//# sourceMappingURL=rules.js.map

package/dist/features/version-manager/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../src/features/version-manager/rules.ts"],"names":[],"mappings":"AAGA;;;4DAG4D;AAC5D,MAAM,UAAU,qBAAqB,CAAC,KAAyB,EAAE,MAAc;IAC7E,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAChG,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE;YACjC,KAAK,EAAE,OAAO;YACd,GAAG,EAAE,SAAS;YACd,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;SAClB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;AACH,CAAC;AAED;;kEAEkE;AAClE,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC5C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,sBAAsB,CAAC,MAAqB;IAC1D,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,sBAAsB,CACpC,QAA6B;IAE7B,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED;iDACiD;AACjD,MAAM,UAAU,iBAAiB,CAC/B,QAA6B;IAE7B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IACxC,KAAK,MAAM,OAAO,IAAI,QAAQ;QAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAC7D,OAAO,GAAG,CAAC;AACb,CAAC;AAED;mCACmC;AACnC,MAAM,UAAU,mBAAmB,CACjC,OAAoC,EACpC,WAA0C;IAE1C,IAAI,CAAC,OAAO,EAAE,oBAAoB;QAAE,OAAO,IAAI,CAAC;IAChD,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,oBAAoB,CAAC,IAAI,IAAI,CAAC;AAC/D,CAAC;AAED;;;qDAGqD;AACrD,MAAM,UAAU,sBAAsB,CACpC,QAA6B,EAC7B,WAA0C,EAC1C,UAAyB;IAEzB,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;IAChC,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5E,CAAC;AAED;gCACgC;AAChC,MAAM,UAAU,uBAAuB,CAAC,YAAoB,EAAE,SAAiB;IAC7E,OAAO,YAAY,GAAG,SAAS,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAA6B,EAC7B,MAAc,EACd,QAAuC;IAEvC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,IAAI,CAAC,UAAU;QAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;AAC5F,CAAC;AASD;;+EAE+E;AAC/E,MAAM,UAAU,iBAAiB,CAC/B,KAAqC;IAErC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,6BAA6B,EAAE,GAAG,KAAK,CAAC;IAC5F,OAAO,CACL,CAAC,eAAe;QAChB,eAAe,CAAC,OAAO;QACvB,SAAS;QACT,cAAc;QACd,CAAC,6BAA6B,CAC/B,CAAC;AACJ,CAAC;AAED;;kDAEkD;AAClD,MAAM,UAAU,uBAAuB,CACrC,UAAyB,EACzB,wBAAuC,EACvC,eAA8B;IAE9B,OAAO,OAAO,CAAC,UAAU,IAAI,wBAAwB,KAAK,UAAU,IAAI,eAAe,CAAC,CAAC;AAC3F,CAAC;AAED;;6CAE6C;AAC7C,MAAM,UAAU,kBAAkB,CAAC,OAAkC,EAAE,EAAU;IAC/E,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAE,CAAC;AACnE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAsB,EACtB,YAAoB,EACpB,UAAyC,EACzC,aAAqB;IAErB,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,YAAY,CAAC;IACzD,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,MAAM;QAAE,OAAO,YAAY,CAAC;IAChF,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,KAAK,GAAG,aAAa,CAAC,CAAC;IACrE,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7F,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC;AAED;;4EAE4E;AAC5E,MAAM,UAAU,oBAAoB,CAClC,MAAsB,EACtB,cAAsB,EACtB,YAAoB;IAEpB,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAC7B,OAAO;QACL,0BAA0B,EAAE,GAAG,MAAM,CAAC,KAAK,IAAI;QAC/C,2BAA2B,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI;QACjD,iBAAiB,EAAE,cAAc;QACjC,sBAAsB,EAAE,YAAY;KACrC,CAAC;AACJ,CAAC;AAED;;;;2EAI2E;AAC3E,MAAM,UAAU,sBAAsB,CACpC,MAAsB,EACtB,YAAoB;IAEpB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO;YACL,KAAK,EAAE,GAAG,GAAG,GAAG,YAAY,GAAG;YAC/B,MAAM,EAAE,GAAG,GAAG,GAAG,YAAY,GAAG;YAChC,SAAS,EAAE,SAAS,YAAY,GAAG;YACnC,eAAe,EAAE,KAAK;SACvB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,KAAK,EAAE,+BAA+B;QACtC,MAAM,EAAE,gCAAgC;QACxC,SAAS,EAAE,gCAAgC;QAC3C,eAAe,EAAE,KAAK;KACvB,CAAC;AACJ,CAAC"}

package/dist/features/version-manager/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Generic types for the "version list + cached-preview + restore + search"
+ * modal shell.
+ *
+ * Source: a vendored OD file-viewer god-component's version-history modal
+ * (`FileVersionManagerModal`). See `packages/ui/source-map.md`'s
+ * `html-viewer` classification section for full provenance, the prior
+ * (incorrect) "OD-specific, saturated with analytics/deploy" filing this
+ * corrects, and what was deliberately left as a host-injected port.
+ */
+/** How a version came to exist. Kept as a 3-value union matching the
+ *  source's actual vocabulary — a host with a different taxonomy widens
+ *  this via its own `TVersion` type parameter. */
+export type VersionSource = 'ai' | 'manual' | 'restore';
+/** The minimal version-record shape every consumer of this feature needs.
+ *  A host's real version type (with e.g. author, diff stats, artifact
+ *  status) is expected to widen this, not replace it — same "host widens
+ *  the minimal shape" story as `ViewerFileRef` in `features/viewer-shell/`. */
+export interface VersionRecord {
+    id: string;
+    version: number;
+    /** Epoch millis. */
+    createdAt: number;
+    current: boolean;
+    label?: string | undefined;
+    /** The AI-generation prompt that produced this version, if any. */
+    prompt?: string | null | undefined;
+    source: VersionSource;
+    /** Id of the version this one was restored from, if `source === 'restore'`. */
+    restoreFromVersionId?: string | null | undefined;
+}
+/**
+ * Identifies which host-side entity's version history this instance shows.
+ * Deliberately NOT `ViewerFileRef` (`features/viewer-shell/`'s file-ref
+ * shape) — that type carries `size`/`mtime` for cache-busting a *current*
+ * file body, neither of which this feature needs; this feature instead
+ * needs an opaque host-scoped id (e.g. an OD project id) alongside the
+ * file name, a different shape entirely. Reusing `ViewerFileRef` here
+ * would force every host to fabricate a fake `size`/`mtime` pair.
+ */
+export interface VersionManagerFileRef {
+    /** Opaque identifier passed through verbatim to the port — e.g. a
+     *  project/workspace id. Not interpreted by this feature. */
+    scopeId: string;
+    name: string;
+}
+export interface VersionRestoreWarning {
+    message: string;
+}
+export interface VersionRestoreResult<TVersion extends VersionRecord = VersionRecord> {
+    /** The version record produced by the restore (a new "restore" version,
+     *  in the source's model) — falls back to the version that was restored
+     *  from if the port doesn't return one. */
+    version?: TVersion;
+    /** A non-fatal warning to surface after a restore that otherwise
+     *  succeeded (e.g. "a snapshot capture failed") — mirrors the source's
+     *  `versionWarning` field. Presence of a warning keeps the modal open
+     *  instead of closing it. */
+    warning?: VersionRestoreWarning;
+}
+/** Measured size of the preview canvas the scaled iframe fits inside. */
+export interface PreviewCanvasSize {
+    width: number;
+    height: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/version-manager/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/version-manager/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;kDAEkD;AAClD,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAC;AAExD;;;+EAG+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,+EAA+E;IAC/E,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC;iEAC6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa;IAClF;;+CAE2C;IAC3C,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB;;;iCAG6B;IAC7B,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/features/version-manager/types.js

@@ -0,0 +1,12 @@
+/**
+ * Generic types for the "version list + cached-preview + restore + search"
+ * modal shell.
+ *
+ * Source: a vendored OD file-viewer god-component's version-history modal
+ * (`FileVersionManagerModal`). See `packages/ui/source-map.md`'s
+ * `html-viewer` classification section for full provenance, the prior
+ * (incorrect) "OD-specific, saturated with analytics/deploy" filing this
+ * corrects, and what was deliberately left as a host-injected port.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/features/version-manager/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/features/version-manager/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}