@makershq/react 0.0.0-stage → 0.3.1

package/dist/tauri/host-controller.js

@@ -0,0 +1,951 @@
+/** Coordinates native child windows while the main app retains its updater resources.
+ *
+ * Owns preferences, narrowly authenticated events and exact installed-version presentation.
+ *
+ * Keep callback execution in this host; child windows receive serializable state only.
+ */
+import { getName, getVersion } from '@tauri-apps/api/app';
+import { emitTo } from '@tauri-apps/api/event';
+import { getCurrentWebviewWindow, WebviewWindow, } from '@tauri-apps/api/webviewWindow';
+import { load } from '@tauri-apps/plugin-store';
+import { valid } from 'semver';
+import { fetchReleasePage } from '../api.js';
+import { isInstalledUpgrade, readPreferences } from './preferences.js';
+import { ACTION_EVENT, CHILD_PREFIX, CHILD_QUERY, isActionEnvelope, STATE_EVENT, } from './protocol.js';
+import { PEER_CONNECT_EVENT, PEER_ACTION_EVENT, PEER_RESULT_EVENT, isPeerLabel, isPeerAction, } from './peer-protocol.js';
+const hostLifecycles = new Map();
+const NATIVE_THEME_ERROR = 'Native window appearance could not be updated. Check the main window theme capability.';
+/** Host-only state owner for one project and native main window. */
+export class NativeHostController {
+    projectId;
+    updater;
+    hostWindowLabel;
+    presentation;
+    state;
+    snapshotRevision = 0;
+    presentationGeneration = 0;
+    latestUpdateGeneration = 0;
+    automaticAttempt = 0;
+    listeners = new Set();
+    children = new Map();
+    peers = new Map();
+    openings = new Map();
+    store = null;
+    disposers = [];
+    disposed = false;
+    automaticVersion = null;
+    automaticPending = false;
+    persistence = Promise.resolve();
+    operation = 0;
+    installation = null;
+    ready;
+    initializationError = null;
+    releaseLease;
+    disposal = null;
+    hostWindow = null;
+    nativeThemeUpdates = null;
+    nativeThemeRequest = 0;
+    /** Initializes the single host and its app-local preference store.
+     * @param projectId - Public release-note project.
+     * @param icon - Consumer-owned app icon URL.
+     * @param updater - Consumer-owned updater callbacks.
+     * @param theme - App's selected theme.
+     * @param hostWindowLabel - Label of the sole callback-owning native window.
+     * @param presentation - Fixed presentation policy for this lifecycle.
+     */
+    constructor(projectId, icon, updater, theme, hostWindowLabel, presentation = 'native') {
+        this.projectId = projectId;
+        this.updater = updater;
+        this.hostWindowLabel = hostWindowLabel;
+        this.presentation = presentation;
+        this.state = {
+            ready: false,
+            presentation,
+            readerRequest: null,
+            updateRequest: null,
+            projectId,
+            name: '',
+            currentVersion: '',
+            icon,
+            theme,
+            preferences: readPreferences(null),
+            status: 'idle',
+            candidate: null,
+            progress: null,
+            canCancel: Boolean(updater.cancel),
+            error: null,
+            readerVersion: null,
+        };
+        const previous = hostLifecycles.get(hostWindowLabel) ?? Promise.resolve();
+        let releaseLease;
+        const lease = new Promise((resolve) => {
+            releaseLease = resolve;
+        });
+        this.releaseLease = () => {
+            releaseLease();
+            if (hostLifecycles.get(hostWindowLabel) === lease)
+                hostLifecycles.delete(hostWindowLabel);
+        };
+        hostLifecycles.set(hostWindowLabel, lease);
+        // Official Store.load caches one resource per path. A replacement host must wait
+        // until its predecessor finishes initialization and closes that shared resource.
+        this.ready = previous.then(() => this.disposed ? undefined : this.initialize());
+    }
+    /** Subscribes to host state.
+     * @param listener - React external-store listener.
+     * @returns Unsubscribe callback.
+     */
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    /** Returns the stable current state snapshot.
+     * @returns Serializable native presentation state.
+     */
+    getSnapshot = () => this.state;
+    async initialize() {
+        try {
+            const current = getCurrentWebviewWindow();
+            if (current.label !== this.hostWindowLabel)
+                throw new Error('ReleaseNotesHost must run in its configured host window.');
+            if (this.presentation === 'native')
+                this.hostWindow = current;
+            const [name, currentVersion] = await Promise.all([
+                getName(),
+                getVersion(),
+            ]);
+            if (this.disposed)
+                return;
+            const store = await load('makers-hq-release-notes.json', {
+                autoSave: false,
+                defaults: {},
+            });
+            if (this.disposed) {
+                await store.close();
+                return;
+            }
+            this.store = store;
+            const preferences = readPreferences(await store.get(this.projectId));
+            if (this.disposed)
+                return;
+            this.patch({ name, currentVersion, preferences });
+            void this.synchronizeNativeTheme();
+            const unlisten = await current.listen(ACTION_EVENT, ({ payload }) => {
+                for (const [kind, record] of this.children) {
+                    if (isActionEnvelope(payload, CHILD_PREFIX + kind, record.token)) {
+                        void this.dispatch(kind, payload.action, payload.generation).catch(() => this.fail('The action could not be completed. Please try again.'));
+                        break;
+                    }
+                }
+            });
+            if (this.disposed) {
+                unlisten();
+                return;
+            }
+            this.disposers.push(unlisten);
+            const connectCleanup = await current.listen(PEER_CONNECT_EVENT, ({ payload }) => {
+                void this.connectPeer(payload).catch(() => undefined);
+            });
+            if (this.disposed) {
+                connectCleanup();
+                return;
+            }
+            this.disposers.push(connectCleanup);
+            const actionCleanup = await current.listen(PEER_ACTION_EVENT, ({ payload }) => {
+                void this.dispatchPeer(payload).catch(() => undefined);
+            });
+            if (this.disposed) {
+                actionCleanup();
+                return;
+            }
+            this.disposers.push(actionCleanup);
+            const focusCleanup = await current.onFocusChanged(({ payload }) => {
+                if (payload)
+                    void this.retryAutomatic();
+            });
+            if (this.disposed) {
+                focusCleanup();
+                return;
+            }
+            this.disposers.push(focusCleanup);
+            const online = () => void this.retryAutomatic();
+            window.addEventListener('online', online);
+            this.disposers.push(() => window.removeEventListener('online', online));
+            if (!preferences.acknowledgedVersion ||
+                (!preferences.showAfterUpdate &&
+                    isInstalledUpgrade(currentVersion, preferences.acknowledgedVersion))) {
+                await this.savePreferences({ acknowledgedVersion: currentVersion });
+            }
+            this.automaticPending =
+                preferences.showAfterUpdate &&
+                    isInstalledUpgrade(currentVersion, preferences.acknowledgedVersion);
+            this.patch({ ready: true });
+            // Do not await the public API during host initialization or block manual actions.
+            void this.retryAutomatic();
+        }
+        catch {
+            if (!this.disposed) {
+                this.initializationError = new Error('Release notes could not start. Check the Tauri app, event, window and store capabilities.');
+                this.fail(this.initializationError.message);
+            }
+        }
+    }
+    patch(patch) {
+        if (this.disposed)
+            return;
+        this.state = { ...this.state, ...patch };
+        this.snapshotRevision++;
+        for (const listener of this.listeners)
+            listener();
+        for (const [label, record] of this.peers)
+            void this.sendPeerState(label, record).catch(() => undefined);
+        for (const [kind, record] of this.children)
+            void this.sendState(kind, record).catch(() => undefined);
+    }
+    fail(message) {
+        this.patch({ status: 'error', error: message, progress: null });
+    }
+    async sendState(kind, record) {
+        await emitTo({ kind: 'WebviewWindow', label: CHILD_PREFIX + kind }, STATE_EVENT, {
+            token: record.token,
+            sender: this.hostWindowLabel,
+            revision: this.snapshotRevision,
+            state: this.state,
+        });
+    }
+    async sendPeerState(label, peer) {
+        await emitTo({ kind: 'WebviewWindow', label }, STATE_EVENT, {
+            sender: this.hostWindowLabel,
+            token: peer.token,
+            connectionNonce: peer.nonce,
+            revision: this.snapshotRevision,
+            state: this.state,
+        });
+    }
+    async connectPeer(value) {
+        if (this.disposed || !value || typeof value !== 'object')
+            return;
+        const message = value;
+        if (!isPeerLabel(message.sender, this.hostWindowLabel) ||
+            typeof message.nonce !== 'string' ||
+            !/^[a-f0-9-]{36}$/.test(message.nonce))
+            return;
+        // Tauri capabilities remain local-only. The nonce response is targeted to the
+        // existing native label, never to a caller-provided URL or a claimed origin.
+        const window = await WebviewWindow.getByLabel(message.sender);
+        if (!window || this.disposed)
+            return;
+        const existing = this.peers.get(message.sender);
+        if (existing?.nonce === message.nonce) {
+            await this.sendPeerState(message.sender, existing);
+            return;
+        }
+        existing?.cleanup?.();
+        const record = {
+            token: crypto.randomUUID(),
+            nonce: message.nonce,
+        };
+        this.peers.set(message.sender, record);
+        const cleanup = await window.once('tauri://destroyed', () => {
+            if (this.peers.get(message.sender) === record)
+                this.peers.delete(message.sender);
+        });
+        if (this.disposed || this.peers.get(message.sender) !== record) {
+            cleanup();
+            return;
+        }
+        record.cleanup = cleanup;
+        await this.sendPeerState(message.sender, record);
+    }
+    async dispatchPeer(value) {
+        if (this.disposed || !value || typeof value !== 'object')
+            return;
+        const message = value;
+        if (!isPeerLabel(message.sender, this.hostWindowLabel) ||
+            typeof message.request !== 'string' ||
+            !/^[a-f0-9-]{36}$/.test(message.request) ||
+            !isPeerAction(message.action))
+            return;
+        const peer = this.peers.get(message.sender);
+        if (!peer || peer.token !== message.token)
+            return;
+        const action = message.action;
+        if (action.type === 'disconnect') {
+            peer.cleanup?.();
+            this.peers.delete(message.sender);
+            return;
+        }
+        let ok = true;
+        try {
+            if (action.type === 'open')
+                await this.openFrom(message.sender);
+            else if (action.type === 'check')
+                await this.check(message.sender);
+            else if (action.type === 'preference')
+                await this.setShowAfterUpdate(action.value);
+            else if (action.type === 'presentation') {
+                if (this.presentation !== 'headless')
+                    throw new Error('Headless presentation is disabled.');
+                await this.presentationAction(action.kind, action.generation, action.action);
+            }
+        }
+        catch {
+            ok = false;
+        }
+        if (!this.disposed && this.peers.get(message.sender) === peer)
+            await emitTo({ kind: 'WebviewWindow', label: message.sender }, PEER_RESULT_EVENT, {
+                sender: this.hostWindowLabel,
+                token: peer.token,
+                request: message.request,
+                ok,
+            });
+    }
+    async savePreferences(preferences) {
+        // Serialize writes so rapid changes cannot persist stale snapshots last.
+        const store = this.store;
+        if (!store)
+            throw new Error('Release-note preference store is unavailable.');
+        const save = this.persistence
+            .catch(() => undefined)
+            .then(async () => {
+            const next = { ...this.state.preferences, ...preferences };
+            await store.set(this.projectId, next);
+            await store.save();
+            this.patch({ preferences: next });
+        });
+        this.persistence = save;
+        await save;
+    }
+    async ensureReady() {
+        await this.ready;
+        if (this.initializationError)
+            throw this.initializationError;
+        if (this.disposed)
+            throw new Error('Release notes host was closed.');
+    }
+    /** Updates consumer callbacks and appearance without recreating native resources.
+     * @param updater - Latest app-owned callbacks.
+     * @param icon - Current app icon URL.
+     * @param theme - Current app theme.
+     */
+    configure(updater, icon, theme) {
+        this.updater = updater;
+        const changed = theme !== this.state.theme;
+        this.patch({
+            icon,
+            theme,
+            canCancel: Boolean(updater.cancel) &&
+                (this.state.status !== 'progress' || this.state.canCancel),
+        });
+        if (changed)
+            void this.synchronizeNativeTheme();
+    }
+    /** Synchronizes consumer theme changes to existing child windows.
+     * @param theme - System, light or dark consumer preference.
+     */
+    setTheme(theme) {
+        const changed = theme !== this.state.theme;
+        this.patch({ theme });
+        if (changed)
+            void this.synchronizeNativeTheme();
+    }
+    // Main is the only native appearance writer. macOS/Linux apply this app-wide;
+    // Windows also needs each SDK window updated. Coalesce changes across IPC waits.
+    synchronizeNativeTheme() {
+        // Headless consumers own every native appearance decision and need no capability.
+        if (this.presentation !== 'native')
+            return Promise.resolve();
+        this.nativeThemeRequest++;
+        if (this.nativeThemeUpdates)
+            return this.nativeThemeUpdates;
+        this.nativeThemeUpdates = Promise.resolve().then(async () => {
+            let handled = 0;
+            try {
+                while (!this.disposed &&
+                    this.hostWindow &&
+                    handled !== this.nativeThemeRequest) {
+                    handled = this.nativeThemeRequest;
+                    const theme = this.state.theme === 'system' ? null : this.state.theme;
+                    const targets = [
+                        { window: this.hostWindow, current: () => true },
+                        ...[...this.children]
+                            .filter(([, record]) => record.created)
+                            .map(([kind, record]) => ({
+                            window: record.window,
+                            current: () => this.children.get(kind) === record,
+                        })),
+                    ];
+                    let failed = false;
+                    for (const target of targets) {
+                        if (this.disposed)
+                            return;
+                        if (!target.current())
+                            continue;
+                        try {
+                            await target.window.setTheme(theme);
+                        }
+                        catch {
+                            if (target.current())
+                                failed = true;
+                        }
+                    }
+                    if (handled !== this.nativeThemeRequest)
+                        continue;
+                    // Appearance failure must not interrupt an active update or hide its error.
+                    if (failed && !this.state.error)
+                        this.patch({ error: NATIVE_THEME_ERROR });
+                    else if (!failed && this.state.error === NATIVE_THEME_ERROR)
+                        this.patch({ error: null });
+                }
+            }
+            finally {
+                this.nativeThemeUpdates = null;
+            }
+        });
+        return this.nativeThemeUpdates;
+    }
+    /** Opens or focuses the single changelog window.
+     * @returns Completion after the native window is ready.
+     */
+    open = () => this.openFrom(this.hostWindowLabel);
+    async openFrom(originLabel) {
+        await this.ensureReady();
+        this.automaticVersion = null;
+        this.automaticAttempt++;
+        this.requestPresentation('reader', originLabel, { readerVersion: null });
+        try {
+            if (this.presentation === 'native')
+                await this.openWindow('reader', originLabel);
+        }
+        catch (error) {
+            this.patch({
+                error: 'The release notes window could not open. Check Tauri window creation and event capabilities.',
+            });
+            throw error;
+        }
+    }
+    /** Offers a background updater candidate while respecting the skipped version.
+     * @param candidate - Version supplied by the consumer's existing background checker.
+     * @param candidate.version - Exact candidate version.
+     * @param candidate.notes - Optional plain-text updater notes.
+     * @returns Completion after a matching update window is open, or a quiet skip.
+     */
+    notifyUpdateAvailable = async (candidate) => {
+        await this.ensureReady();
+        this.validateCandidate(candidate);
+        if (candidate.version === this.state.preferences.skippedVersion ||
+            this.state.status === 'progress')
+            return;
+        this.requestPresentation('update', this.hostWindowLabel, {
+            candidate: {
+                version: candidate.version,
+                ...(candidate.notes ? { notes: candidate.notes } : {}),
+            },
+            status: 'available',
+            error: null,
+            progress: null,
+        });
+        try {
+            if (this.presentation === 'native')
+                await this.openWindow('update');
+        }
+        catch (error) {
+            this.patch({
+                error: 'The update window could not open. Check Tauri window creation and event capabilities.',
+            });
+            throw error;
+        }
+    };
+    validateCandidate(candidate) {
+        if (!candidate ||
+            !valid(candidate.version) ||
+            (candidate.notes !== undefined &&
+                (typeof candidate.notes !== 'string' ||
+                    candidate.notes.length > 1_000_000)))
+            throw new Error('The app updater returned an invalid update candidate.');
+    }
+    /** Runs an explicit user check, bypassing skipped-version suppression.
+     * @param originLabel - Existing settings window to receive focus after closing the update.
+     * @returns Completion after the updater result is shown.
+     */
+    check = async (originLabel = this.hostWindowLabel) => {
+        await this.ensureReady();
+        if (this.state.status === 'checking' || this.state.status === 'progress')
+            return;
+        const existingUpdate = this.children.get('update');
+        if (existingUpdate)
+            existingUpdate.originLabel = originLabel;
+        const request = this.requestPresentation('update', originLabel, {
+            status: 'checking',
+            error: null,
+            candidate: null,
+        });
+        try {
+            const candidate = await this.updater.check();
+            if (this.disposed || this.latestUpdateGeneration !== request.generation)
+                return;
+            if (candidate)
+                this.validateCandidate(candidate);
+            this.patch({
+                candidate,
+                status: candidate ? 'available' : 'current',
+                progress: null,
+            });
+            if (this.presentation === 'native' &&
+                this.state.updateRequest === request)
+                await this.openWindow('update', originLabel);
+        }
+        catch {
+            if (this.latestUpdateGeneration !== request.generation)
+                return;
+            this.fail('Could not check for updates. Check your connection and try again.');
+        }
+    };
+    /** Saves the shared after-update preference.
+     * @param value - Whether future upgrades should open a changelog.
+     * @returns Completion after persistence and child synchronization.
+     */
+    setShowAfterUpdate = async (value) => {
+        await this.ensureReady();
+        try {
+            await this.savePreferences({ showAfterUpdate: value });
+        }
+        catch (error) {
+            this.patch({
+                error: 'Your release-note preference could not be saved. Please try again.',
+            });
+            throw error;
+        }
+    };
+    async retryAutomatic() {
+        if (!this.automaticPending ||
+            this.disposed ||
+            this.automaticVersion ||
+            this.state.readerRequest)
+            return;
+        this.automaticVersion = this.state.currentVersion;
+        const attempt = ++this.automaticAttempt;
+        let request = null;
+        try {
+            const page = await fetchReleasePage(this.projectId, {
+                version: this.state.currentVersion,
+            });
+            if (this.disposed ||
+                attempt !== this.automaticAttempt ||
+                !this.state.preferences.showAfterUpdate ||
+                !page.items.some((release) => release.version === this.state.currentVersion)) {
+                if (attempt === this.automaticAttempt)
+                    this.automaticVersion = null;
+                return;
+            }
+            request = this.requestPresentation('reader', this.hostWindowLabel, {
+                readerVersion: this.state.currentVersion,
+            });
+            if (this.presentation === 'native')
+                await this.openWindow('reader');
+        }
+        catch {
+            // A failed child must not leave an invisible request blocking future retries.
+            if (request)
+                this.dismissPresentation('reader', request.generation);
+            // Missing publication or connectivity defers the exact-version acknowledgement.
+            if (attempt === this.automaticAttempt)
+                this.automaticVersion = null;
+        }
+    }
+    requestPresentation(kind, originWindowLabel, patch = {}) {
+        const request = {
+            generation: ++this.presentationGeneration,
+            originWindowLabel,
+        };
+        if (kind === 'update')
+            this.latestUpdateGeneration = request.generation;
+        this.patch({
+            ...patch,
+            ...(kind === 'reader'
+                ? { readerRequest: request }
+                : { updateRequest: request }),
+        });
+        return request;
+    }
+    settleUpdatePresentation(originWindowLabel, patch) {
+        if (this.state.updateRequest)
+            this.requestPresentation('update', originWindowLabel, patch);
+        else
+            this.patch(patch);
+    }
+    dismissPresentation(kind, generation) {
+        const request = kind === 'reader' ? this.state.readerRequest : this.state.updateRequest;
+        if (request?.generation !== generation)
+            return;
+        if (kind === 'reader') {
+            this.automaticAttempt++;
+            if (this.automaticPending)
+                this.automaticVersion = null;
+            this.patch({ readerRequest: null });
+        }
+        else
+            this.patch({ updateRequest: null });
+    }
+    /** Accepts one action bound to the active headless presentation.
+     * @param kind - Reader or update presentation.
+     * @param generation - Private presentation identity captured by the hook.
+     * @param action - Bounded presentation command.
+     * @param action.type - Fixed command discriminator.
+     * @param action.version - Exact displayed candidate or rendered release version.
+     * @param action.cached - Whether rendered content came from offline storage.
+     * @returns Command acceptance; installation and cancellation progress through shared state.
+     */
+    presentationAction = async (kind, generation, action) => {
+        await this.ensureReady();
+        if (this.presentation !== 'headless')
+            throw new Error('Use headless presentation actions only in headless mode.');
+        const request = kind === 'reader' ? this.state.readerRequest : this.state.updateRequest;
+        if (request?.generation !== generation)
+            return;
+        if (action.type === 'dismiss') {
+            this.dismissPresentation(kind, generation);
+            return;
+        }
+        if (kind === 'reader') {
+            if (action.type === 'rendered' && !action.cached) {
+                try {
+                    await this.dispatch(kind, { type: 'rendered', version: action.version }, generation);
+                }
+                catch {
+                    this.patch({
+                        error: 'The release-note acknowledgment could not be saved. Please try again.',
+                    });
+                }
+            }
+            return;
+        }
+        if (action.type === 'rendered')
+            return;
+        const candidate = this.state.candidate;
+        if ((action.type === 'install' || action.type === 'skip') && !candidate)
+            return;
+        const command = action.type === 'install' || action.type === 'skip'
+            ? { type: action.type, version: action.version }
+            : { type: 'cancel' };
+        if (action.type === 'install' || action.type === 'cancel') {
+            void this.dispatch(kind, command, generation).catch(() => this.fail('The action could not be completed. Please try again.'));
+        }
+        else {
+            try {
+                await this.dispatch(kind, command, generation);
+            }
+            catch (error) {
+                this.patch({
+                    error: 'The update preference could not be saved. Please try again.',
+                });
+                throw error;
+            }
+        }
+    };
+    async openWindow(kind, originLabel = this.hostWindowLabel) {
+        if (this.disposed)
+            throw new Error('Release notes host was closed.');
+        const opening = this.openings.get(kind);
+        if (opening) {
+            await opening;
+            const record = this.children.get(kind);
+            if (record) {
+                record.originLabel = originLabel;
+                await record.window.setFocus();
+            }
+            return;
+        }
+        const task = this.createOrFocus(kind, originLabel);
+        this.openings.set(kind, task);
+        try {
+            await task;
+        }
+        finally {
+            this.openings.delete(kind);
+        }
+    }
+    async createOrFocus(kind, originLabel) {
+        const label = CHILD_PREFIX + kind;
+        const existing = await WebviewWindow.getByLabel(label);
+        if (this.disposed)
+            return;
+        if (existing && this.children.has(kind)) {
+            const record = this.children.get(kind);
+            record.originLabel = originLabel;
+            await this.synchronizeNativeTheme();
+            if (this.disposed || this.children.get(kind) !== record)
+                return;
+            await existing.show();
+            await existing.setFocus();
+            await this.sendState(kind, record);
+            return;
+        }
+        if (existing)
+            await existing.destroy();
+        const url = new URL(window.location.href);
+        // A child uses the host's exact entry point, with no remote URL or app navigation.
+        url.searchParams.set(CHILD_QUERY, kind);
+        url.searchParams.set('__makers_hq_host', this.hostWindowLabel);
+        const token = crypto.randomUUID();
+        url.searchParams.set('__makers_hq_token', token);
+        const child = new WebviewWindow(label, {
+            url: url.href,
+            title: kind === 'reader' ? `New in ${this.state.name}` : 'Software update',
+            width: 680,
+            height: 620,
+            minWidth: 360,
+            minHeight: 420,
+            decorations: true,
+            // On macOS, keep native controls without Tauri's default full-size content
+            // view, which can leave standard title bars light despite native Dark theme.
+            titleBarStyle: 'transparent',
+            ...(this.state.theme === 'system' ? {} : { theme: this.state.theme }),
+            visible: false,
+            center: true,
+        });
+        const record = {
+            window: child,
+            token,
+            originLabel,
+            created: false,
+        };
+        this.children.set(kind, record);
+        try {
+            await new Promise((resolve, reject) => {
+                let createdCleanup;
+                let errorCleanup;
+                const timer = setTimeout(() => {
+                    createdCleanup?.();
+                    errorCleanup?.();
+                    reject(new Error('Native release notes window timed out. Check window creation capabilities.'));
+                }, 15000);
+                void child
+                    .once('tauri://created', () => {
+                    clearTimeout(timer);
+                    errorCleanup?.();
+                    resolve();
+                })
+                    .then((cleanup) => {
+                    createdCleanup = cleanup;
+                });
+                void child
+                    .once('tauri://error', () => {
+                    clearTimeout(timer);
+                    createdCleanup?.();
+                    reject(new Error('Native release notes window creation failed. Check capabilities.'));
+                })
+                    .then((cleanup) => {
+                    errorCleanup = cleanup;
+                });
+            });
+            if (this.disposed) {
+                await child.destroy();
+                return;
+            }
+            record.created = true;
+            await this.synchronizeNativeTheme();
+            if (this.disposed) {
+                await child.destroy();
+                return;
+            }
+            record.cleanup = await child.once('tauri://destroyed', () => {
+                if (this.children.get(kind) !== record)
+                    return;
+                this.children.delete(kind);
+                const request = kind === 'reader'
+                    ? this.state.readerRequest
+                    : this.state.updateRequest;
+                if (request)
+                    this.dismissPresentation(kind, request.generation);
+                void WebviewWindow.getByLabel(record.originLabel)
+                    .then((origin) => origin?.setFocus())
+                    .catch(() => undefined);
+            });
+            await child.show();
+            await child.setFocus();
+        }
+        catch (error) {
+            this.children.delete(kind);
+            await child.destroy().catch(() => undefined);
+            throw error;
+        }
+    }
+    async dispatch(kind, action, generation) {
+        if (action.type === 'ready') {
+            const record = this.children.get(kind);
+            if (record)
+                await this.sendState(kind, record);
+            return;
+        }
+        if (action.type === 'preference') {
+            await this.setShowAfterUpdate(action.value);
+            return;
+        }
+        if (action.type === 'open-reader') {
+            await this.openFrom(this.children.get(kind)?.originLabel ?? this.hostWindowLabel);
+            return;
+        }
+        if (action.type === 'check') {
+            await this.check(this.children.get(kind)?.originLabel ?? this.hostWindowLabel);
+            return;
+        }
+        const request = kind === 'reader' ? this.state.readerRequest : this.state.updateRequest;
+        if (!request || request.generation !== generation)
+            return;
+        if (action.type === 'rendered' && kind === 'reader') {
+            if (action.version === this.automaticVersion &&
+                action.version === this.state.currentVersion &&
+                this.automaticPending) {
+                await this.savePreferences({ acknowledgedVersion: action.version });
+                this.automaticPending = false;
+                this.automaticVersion = null;
+            }
+            return;
+        }
+        if (kind !== 'update')
+            return;
+        if (action.type === 'cancel' &&
+            this.state.status === 'progress' &&
+            this.state.progress?.phase === 'downloading' &&
+            this.updater.cancel &&
+            this.state.canCancel) {
+            const installation = this.installation;
+            this.requestPresentation('update', request.originWindowLabel, {
+                canCancel: false,
+            });
+            const operation = ++this.operation;
+            try {
+                await this.updater.cancel();
+                if (operation === this.operation) {
+                    this.installation = null;
+                    this.settleUpdatePresentation(request.originWindowLabel, {
+                        status: 'available',
+                        progress: null,
+                        canCancel: Boolean(this.updater.cancel),
+                    });
+                }
+            }
+            catch {
+                if (operation === this.operation) {
+                    if (installation?.settled === 'failed')
+                        this.settleUpdatePresentation(request.originWindowLabel, {
+                            status: 'available',
+                            progress: null,
+                            canCancel: Boolean(this.updater.cancel),
+                            error: 'The update stopped, but cancellation could not be confirmed. Please try again.',
+                        });
+                    else {
+                        if (installation)
+                            this.operation = installation.id;
+                        this.patch({
+                            error: 'The download could not be cancelled. The app may still be installing.',
+                            canCancel: false,
+                        });
+                    }
+                }
+            }
+            return;
+        }
+        if (action.type !== 'install' && action.type !== 'skip')
+            return;
+        if (this.state.status !== 'available' ||
+            action.version !== this.state.candidate?.version)
+            return;
+        if (action.type === 'skip') {
+            await this.savePreferences({ skippedVersion: action.version });
+            if (this.state.updateRequest === request) {
+                this.dismissPresentation('update', request.generation);
+                await this.children.get('update')?.window.close();
+            }
+            return;
+        }
+        const operation = ++this.operation;
+        const installation = { id: operation, settled: 'pending' };
+        this.installation = installation;
+        this.requestPresentation('update', request.originWindowLabel, {
+            status: 'progress',
+            canCancel: Boolean(this.updater.cancel),
+            progress: { phase: 'downloading', downloadedBytes: 0 },
+            error: null,
+        });
+        try {
+            await this.updater.install(action.version, (progress) => {
+                if (operation === this.operation && validProgress(progress))
+                    this.patch({ progress });
+            });
+            installation.settled = 'succeeded';
+            // A successful consumer normally restarts; no SDK restart or second confirmation.
+        }
+        catch {
+            installation.settled = 'failed';
+            if (operation === this.operation)
+                this.settleUpdatePresentation(request.originWindowLabel, {
+                    status: 'available',
+                    progress: null,
+                    canCancel: Boolean(this.updater.cancel),
+                    error: this.state.progress?.phase === 'restarting'
+                        ? 'The update is installed, but the app could not restart. Try again to restart it.'
+                        : 'The update could not be installed. Please try again.',
+                });
+        }
+    }
+    /** Releases listeners, local resources and native child windows on host unmount.
+     * @returns Completion after pending preference/appearance writes and child cleanup.
+     */
+    dispose() {
+        if (!this.disposal)
+            this.disposal = this.cleanup();
+        return this.disposal;
+    }
+    async cleanup() {
+        this.disposed = true;
+        await this.ready;
+        this.operation++;
+        for (const cleanup of this.disposers)
+            cleanup();
+        this.disposers = [];
+        // A replacement host acquires its lease only after old native writes settle.
+        await this.nativeThemeUpdates;
+        for (const record of this.children.values()) {
+            record.cleanup?.();
+            await record.window.destroy().catch(() => undefined);
+        }
+        this.children.clear();
+        for (const peer of this.peers.values())
+            peer.cleanup?.();
+        this.peers.clear();
+        await this.persistence.catch(() => undefined);
+        try {
+            await this.store?.close();
+        }
+        finally {
+            this.listeners.clear();
+            this.releaseLease();
+        }
+    }
+}
+function validProgress(progress) {
+    if (!progress || typeof progress !== 'object')
+        return false;
+    if (progress.phase === 'installing' || progress.phase === 'restarting')
+        return true;
+    return (progress.phase === 'downloading' &&
+        Number.isFinite(progress.downloadedBytes) &&
+        progress.downloadedBytes >= 0 &&
+        (progress.totalBytes === undefined ||
+            (Number.isFinite(progress.totalBytes) &&
+                progress.totalBytes >= progress.downloadedBytes)));
+}
+/** Creates the private native lifecycle owner for a single host window.
+ * @param projectId - Public release-note project.
+ * @param icon - Consumer icon URL.
+ * @param updater - Consumer updater callbacks.
+ * @param theme - Consumer theme.
+ * @param hostWindowLabel - Callback-owning native window.
+ * @param presentation - Fixed native or headless presentation policy.
+ * @returns Internal lifecycle owner; never exported by the package entry point.
+ */
+export function createNativeHostController(projectId, icon, updater, theme, hostWindowLabel, presentation = 'native') {
+    return new NativeHostController(projectId, icon, updater, theme, hostWindowLabel, presentation);
+}