diff --git a/AGENTS.md b/AGENTS.md
index 61e2f12..d97a8f6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,6 +26,10 @@ bun).
   without updating README's privacy section.
 - Follow the Pickforge design system: ember `#FF7A1A` accent, Geist/Geist Mono,
   tokens over raw values.
+- Async waits built on event listeners must re-check the awaited condition
+  right after the listener registers (the state can change in the gap) and
+  re-verify every condition on each event instead of trusting the event
+  payload alone — pickgauge#70's eligibility gate shipped both mistakes.
 
 ## Releasing
 
diff --git a/bun.lock b/bun.lock
index 71e63f8..c14e4ac 100644
--- a/bun.lock
+++ b/bun.lock
@@ -6,6 +6,8 @@
       "name": "pickgauge",
       "dependencies": {
         "@pickforge/brand": "0.2.1",
+        "@pickforge/flags": "^0.4.0",
+        "@pickforge/tauri-updater": "^0.12.0",
         "@tauri-apps/api": "^2.9.0",
         "@tauri-apps/plugin-process": "^2.3.1",
         "@tauri-apps/plugin-updater": "^2.10.1",
@@ -138,8 +140,12 @@
 
     "@pickforge/brand": ["@pickforge/brand@0.2.1", "", { "dependencies": { "@fontsource/geist-mono": "^5.2.8", "@fontsource/geist-sans": "^5.2.5" } }, "sha512-8VASbOUFJKUkb2zVvqto7aPynyICISCMzrh8jMRcvovtKNpzbLMrZ2xS7eeIPQyVs5NRbJ0457Vb0HQC+sIhQQ=="],
 
+    "@pickforge/flags": ["@pickforge/flags@0.4.0", "", {}, "sha512-Z0nlxk3/0HXA7em8+ZQ+BV3jfF2U0E8uCdDPdyW2WdbMHe2pF7rgukTAIAyAZexEB3c7SATEYCbrnNsEd9V9Nw=="],
+
     "@pickforge/tauri-release": ["@pickforge/tauri-release@0.3.0", "", { "bin": { "pickforge-tauri-release": "dist/cli.js" } }, "sha512-LTpsp6+zB9WU9eflvWH8tRFGNCJmiQW7ULYNnffQYCgfZ3fSqF33yDBKW38WdXdlyDBEcYpFnYjkw0+YnLob8Q=="],
 
+    "@pickforge/tauri-updater": ["@pickforge/tauri-updater@0.12.0", "", {}, "sha512-3q5SgSAJBV/ctpxFGKUvKOHZ6uIszhgO3BPajgA+BrffulARzrW9Uv4fXRy4TFWoV83LNlSy9GVnCi6dYWnJBw=="],
+
     "@rollup/rollup-android-arm-eabi": ["@rollup/rollup-android-arm-eabi@4.62.2", "", { "os": "android", "cpu": "arm" }, "sha512-6o7ZLZK+BeenkZCFNDXqpbjw9bD6nuWonvS/lwQJp7NoVVxm6p3qE7qQ5jGuBjiFsgvqjD8mZAU5oWxTmbOeOg=="],
 
     "@rollup/rollup-android-arm64": ["@rollup/rollup-android-arm64@4.62.2", "", { "os": "android", "cpu": "arm64" }, "sha512-BaH7BllCACHoH1LguOU56UItGfUWjujlO65kS9LAodViaN4bwIKd7oeW/ZHJ/4ljr/7MIiENnNy3HJ0zXv8Zkw=="],
diff --git a/docs/release-evidence/update-dialog-available-1000x700.png b/docs/release-evidence/update-dialog-available-1000x700.png
new file mode 100644
index 0000000..fa338ea
Binary files /dev/null and b/docs/release-evidence/update-dialog-available-1000x700.png differ
diff --git a/docs/release-evidence/update-dialog-available-820x580.png b/docs/release-evidence/update-dialog-available-820x580.png
new file mode 100644
index 0000000..fa43f4e
Binary files /dev/null and b/docs/release-evidence/update-dialog-available-820x580.png differ
diff --git a/docs/release-evidence/update-dialog-downloading-1000x700.png b/docs/release-evidence/update-dialog-downloading-1000x700.png
new file mode 100644
index 0000000..46366b0
Binary files /dev/null and b/docs/release-evidence/update-dialog-downloading-1000x700.png differ
diff --git a/docs/release-evidence/update-dialog-downloading-820x580.png b/docs/release-evidence/update-dialog-downloading-820x580.png
new file mode 100644
index 0000000..a6193ca
Binary files /dev/null and b/docs/release-evidence/update-dialog-downloading-820x580.png differ
diff --git a/docs/releases/UNRELEASED.md b/docs/releases/UNRELEASED.md
index 700a3a8..1fb6d62 100644
--- a/docs/releases/UNRELEASED.md
+++ b/docs/releases/UNRELEASED.md
@@ -54,6 +54,17 @@ reset this file.
 
 - Added blocking CI gates for Rust and frontend complexity, coverage, secrets,
   and high/critical dependency advisories, with one required aggregate status.
+- Added the shared `@pickforge/tauri-updater` dialog behind the `studioUpdateDialog`
+  flag (default off; `@pickforge/flags`), part of
+  pickforge/pickforge-platform#36. While off, the legacy `window.confirm`
+  updater in `src/lib/updater.ts` is untouched. When on, `src/lib/updateDialog.ts`
+  mounts the shared controller only on the visible main window: a Tauri
+  window-label check excludes the floating capsule outright, and a hidden
+  main window (tray/login-start) defers the check until its first focus
+  event, mirroring the pre-existing `checkForUpdatesWhenVisible` deferral.
+  One controller per process enforces a single check. A dev-only fixture
+  (`?updateDialogFixture=available|downloading`, tree-shaken from production
+  builds) stands in for a visual baseline since PickGauge has no VRT harness.
 - Headless `usage --json` refreshes independent providers concurrently
   (join-all, emit in fixed service order) so an offline credentialed install
   pays ~max per-provider timeout instead of the sequential sum.
@@ -154,8 +165,18 @@ reset this file.
   candidate by several days. The validated candidate remains installed with a
   checksum-verified rollback backup.
 
+- pickforge/pickforge-platform#36 (PR 5, PickGauge integration): `bun run
+  lint`, `bun run check`, `bun run test` (85 vitest tests including
+  `flags.test.ts` and `updateDialog.test.ts`, covering flag-off default,
+  eligibility for an already-visible main window, capsule exclusion by
+  window label, and hidden-main-window deferral until focus), and `bun run
+  test:coverage` (ratchet holds). No Rust touched.
+
 ### Not yet tested
 
+- pickforge/pickforge-platform#36 (PR 5): owner-gated packaged-update smoke
+  (old build to staged newer build) and design-lead visual acceptance from
+  the dev-only fixture; both deferred to a later PR per the issue's PR plan.
 - Issue #49: real KDE Wayland/XWayland Alt+Tab, taskbar, and pager behavior
   for the float capsule — deferred to Elberte-PC, a live KDE session with
   `qdbus`/`kwriteconfig6` available.
diff --git a/package.json b/package.json
index 5124a26..ef1e8d3 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,8 @@
   },
   "dependencies": {
     "@pickforge/brand": "0.2.1",
+    "@pickforge/flags": "^0.4.0",
+    "@pickforge/tauri-updater": "^0.12.0",
     "@tauri-apps/api": "^2.9.0",
     "@tauri-apps/plugin-process": "^2.3.1",
     "@tauri-apps/plugin-updater": "^2.10.1",
diff --git a/src/App.svelte b/src/App.svelte
index 5c46482..8844cbe 100644
--- a/src/App.svelte
+++ b/src/App.svelte
@@ -18,6 +18,9 @@
     EVENT_SNAPSHOTS,
   } from "./lib/api";
   import { serviceLabels, settingsSaveDisplayState } from "./lib/display";
+  import { flagEnabled } from "./lib/flags";
+  import { mountUpdateDialog, type UpdateDialogHost } from "./lib/updateDialog";
+  import { shouldMountSharedUpdateDialog } from "./lib/updateRouting";
   import {
     browserPreviewSnapshots,
     browserPreviewStateFromSearch,
@@ -47,6 +50,8 @@
   let statusMessage = $state<string | null>(null);
   let statusIsError = $state(false);
   let statusTimer: ReturnType<typeof setTimeout> | null = null;
+  let updateDialogEl: HTMLElement | undefined = $state();
+  const showUpdateDialog = shouldMountSharedUpdateDialog(flagEnabled("studioUpdateDialog"));
 
   const navItems: { id: View; label: string; icon: typeof Gauge }[] = [
     { id: "dashboard", label: "Dashboard", icon: Gauge },
@@ -102,6 +107,10 @@
     let cancelled = false;
     const cleanups: (() => void)[] = [];
 
+    if (showUpdateDialog && updateDialogEl) {
+      mountUpdateDialog(updateDialogEl as unknown as UpdateDialogHost);
+    }
+
     if (!desktopApiAvailable()) {
       snapshots = browserPreviewSnapshots(browserPreviewStateFromSearch(window.location.search));
       loading = false;
@@ -288,6 +297,10 @@
   </div>
 {/if}
 
+{#if showUpdateDialog}
+  <pickforge-update-dialog bind:this={updateDialogEl}></pickforge-update-dialog>
+{/if}
+
 <style>
   .app {
     display: flex;
diff --git a/src/lib/flags.test.ts b/src/lib/flags.test.ts
new file mode 100644
index 0000000..869f66d
--- /dev/null
+++ b/src/lib/flags.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { flagEnabled, setFlagOverride } from "./flags";
+
+describe("studioUpdateDialog flag", () => {
+  it("defaults to off", () => {
+    expect(flagEnabled("studioUpdateDialog")).toBe(false);
+  });
+
+  it("can be flipped on for the current process via an override", () => {
+    setFlagOverride("studioUpdateDialog", true);
+    expect(flagEnabled("studioUpdateDialog")).toBe(true);
+
+    setFlagOverride("studioUpdateDialog", undefined);
+    expect(flagEnabled("studioUpdateDialog")).toBe(false);
+  });
+});
diff --git a/src/lib/flags.ts b/src/lib/flags.ts
new file mode 100644
index 0000000..6f97521
--- /dev/null
+++ b/src/lib/flags.ts
@@ -0,0 +1,25 @@
+// Feature-flag registry (@pickforge/flags). Mirrors the shape PickForge's
+// src/stores/flags.ts uses for the same package: definitions default off
+// unless `default: true` is set, and a launch flip means changing the
+// definition and releasing. PickGauge has no flag-override UI yet, so this
+// uses the package's default in-memory store — an override only lives for
+// the current process, which is enough for manual dev testing.
+import { createFlags } from "@pickforge/flags";
+
+const definitions = {
+  studioUpdateDialog: {
+    description: "Shared Pickforge update dialog (pickforge/pickforge-platform#36)",
+  },
+} as const;
+
+export type FlagKey = keyof typeof definitions;
+
+const flags = createFlags(definitions);
+
+export function flagEnabled(key: FlagKey): boolean {
+  return flags.isEnabled(key);
+}
+
+export function setFlagOverride(key: FlagKey, value: boolean | undefined): void {
+  flags.setOverride(key, value);
+}
diff --git a/src/lib/updateDialog.test.ts b/src/lib/updateDialog.test.ts
new file mode 100644
index 0000000..3f54354
--- /dev/null
+++ b/src/lib/updateDialog.test.ts
@@ -0,0 +1,205 @@
+import { createUpdateController, type UpdateAdapter } from "@pickforge/tauri-updater";
+import { describe, expect, it, vi } from "vitest";
+import {
+  createMainWindowEligibility,
+  MAIN_WINDOW_LABEL,
+  type EligibilityWindow,
+} from "./updateDialog";
+
+/** Stateful fake so tests can flip visibility/focus and emit focus-changed
+ * events the way a real Tauri window would, instead of a fresh mock per
+ * assertion. */
+class FakeEligibilityWindow implements EligibilityWindow {
+  label: string;
+  visible: boolean;
+  focused: boolean;
+  listeners: ((event: { payload: boolean }) => void)[] = [];
+  /** Fires synchronously inside `onFocusChanged`, before it resolves — lets
+   * tests simulate the window's state changing during listener registration. */
+  onRegister?: () => void;
+
+  constructor(label: string, opts: { visible?: boolean; focused?: boolean } = {}) {
+    this.label = label;
+    this.visible = opts.visible ?? false;
+    this.focused = opts.focused ?? false;
+  }
+
+  isVisible = vi.fn(async () => this.visible);
+  isFocused = vi.fn(async () => this.focused);
+  onFocusChanged = vi.fn(async (listener: (event: { payload: boolean }) => void) => {
+    this.listeners.push(listener);
+    this.onRegister?.();
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener);
+    };
+  });
+
+  emitFocus(focused: boolean) {
+    this.focused = focused;
+    for (const listener of this.listeners) {
+      listener({ payload: focused });
+    }
+  }
+}
+
+/** Flushes pending microtasks (the `currentlyEligible()` `Promise.all`
+ * round-trip inside `createMainWindowEligibility` takes a couple of ticks),
+ * more reliably than a fixed number of `await Promise.resolve()` calls. */
+async function flush() {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function fakeAdapter(): UpdateAdapter {
+  return {
+    check: vi.fn(async () => ({ version: "1.2.3" })),
+    downloadAndInstall: vi.fn(async () => {}),
+    relaunch: vi.fn(async () => {}),
+  };
+}
+
+describe("createMainWindowEligibility", () => {
+  it("never becomes eligible for the floating capsule window", async () => {
+    const win = new FakeEligibilityWindow("float", { visible: true, focused: true });
+    const eligibility = createMainWindowEligibility(win, true);
+
+    await expect(eligibility.whenEligible()).resolves.toBe(false);
+    expect(win.isVisible).not.toHaveBeenCalled();
+    expect(win.onFocusChanged).not.toHaveBeenCalled();
+  });
+
+  it("never becomes eligible outside a packaged build", async () => {
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: true, focused: true });
+    const eligibility = createMainWindowEligibility(win, false);
+
+    await expect(eligibility.whenEligible()).resolves.toBe(false);
+    expect(win.isVisible).not.toHaveBeenCalled();
+  });
+
+  it("resolves immediately for an already-visible and focused main window", async () => {
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: true, focused: true });
+    const eligibility = createMainWindowEligibility(win, true);
+
+    await expect(eligibility.whenEligible()).resolves.toBe(true);
+    expect(win.onFocusChanged).not.toHaveBeenCalled();
+  });
+
+  it("defers a visible-but-unfocused main window until it gains focus", async () => {
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: true, focused: false });
+    const eligibility = createMainWindowEligibility(win, true);
+
+    const pending = eligibility.whenEligible();
+    await flush();
+    expect(win.onFocusChanged).toHaveBeenCalledOnce();
+
+    win.emitFocus(true);
+    await expect(pending).resolves.toBe(true);
+  });
+
+  it("stays ineligible when a focus event fires without the window becoming visible", async () => {
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: false, focused: false });
+    const eligibility = createMainWindowEligibility(win, true);
+
+    const pending = eligibility.whenEligible();
+    await flush();
+
+    // Focused, but still hidden (e.g. a tray/login-start window regaining
+    // OS focus while its main window stays hidden) must not resolve.
+    win.emitFocus(true);
+    await flush();
+    let resolved = false;
+    void pending.then(() => {
+      resolved = true;
+    });
+    await flush();
+    expect(resolved).toBe(false);
+
+    // Once it is actually shown and re-focused, it resolves.
+    win.visible = true;
+    win.emitFocus(true);
+    await expect(pending).resolves.toBe(true);
+  });
+
+  it("defers a hidden main window until it is visible and focused, then unlistens", async () => {
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: false, focused: false });
+    const eligibility = createMainWindowEligibility(win, true);
+    const pending = eligibility.whenEligible();
+    await flush();
+
+    // A blur (or other unfocus) event before the window is shown must not
+    // resolve the prompt.
+    win.emitFocus(false);
+    await flush();
+
+    win.visible = true;
+    win.emitFocus(true);
+    await expect(pending).resolves.toBe(true);
+    expect(win.listeners).toHaveLength(0);
+
+    // A later, redundant focus event is ignored (single-flight).
+    const callsBefore = win.onFocusChanged.mock.calls.length;
+    win.emitFocus(true);
+    expect(win.onFocusChanged.mock.calls.length).toBe(callsBefore);
+  });
+
+  it("never resolves for a hidden main window that stays unfocused", async () => {
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: false, focused: false });
+    const eligibility = createMainWindowEligibility(win, true);
+    let resolved = false;
+    void eligibility.whenEligible().then(() => {
+      resolved = true;
+    });
+
+    await flush();
+    expect(resolved).toBe(false);
+  });
+
+  it("does not miss eligibility reached while the focus listener registers", async () => {
+    // The window becomes visible and focused synchronously as a side effect
+    // of registering the listener (simulating a real focus/show event
+    // landing in the gap between the initial check and the listener being
+    // wired up) — whenEligible() must still resolve without waiting for a
+    // subsequent focus event that will never come.
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: false, focused: false });
+    win.onRegister = () => {
+      win.visible = true;
+      win.focused = true;
+    };
+    const eligibility = createMainWindowEligibility(win, true);
+
+    await expect(eligibility.whenEligible()).resolves.toBe(true);
+  });
+});
+
+describe("capsule and hidden-window exclusion through the shared controller", () => {
+  it("never checks for updates when mounted for the floating capsule window", async () => {
+    const adapter = fakeAdapter();
+    const win = new FakeEligibilityWindow("float", { visible: true, focused: true });
+    const controller = createUpdateController({
+      adapter,
+      eligibility: createMainWindowEligibility(win, true),
+    });
+
+    await controller.start();
+
+    expect(adapter.check).not.toHaveBeenCalled();
+    expect(controller.getState()).toEqual({ status: "idle" });
+  });
+
+  it("defers the update check for a hidden main window until it is shown and focused", async () => {
+    const adapter = fakeAdapter();
+    const win = new FakeEligibilityWindow(MAIN_WINDOW_LABEL, { visible: false, focused: false });
+    const controller = createUpdateController({
+      adapter,
+      eligibility: createMainWindowEligibility(win, true),
+    });
+
+    const started = controller.start();
+    await flush();
+    expect(adapter.check).not.toHaveBeenCalled();
+
+    win.visible = true;
+    win.emitFocus(true);
+    await started;
+    expect(adapter.check).toHaveBeenCalledOnce();
+  });
+});
diff --git a/src/lib/updateDialog.ts b/src/lib/updateDialog.ts
new file mode 100644
index 0000000..80a21ba
--- /dev/null
+++ b/src/lib/updateDialog.ts
@@ -0,0 +1,169 @@
+// Wires the shared @pickforge/tauri-updater controller into PickGauge's
+// main window, behind the `studioUpdateDialog` flag (see ./flags.ts). Only
+// App.svelte (the main-window component) imports this module — Float.svelte
+// (the floating capsule) never does, and `createMainWindowEligibility` below
+// additionally checks the real Tauri window label as a second, independent
+// guard against the capsule or a hidden main window ever surfacing the
+// prompt. This replaces the legacy `window.confirm` flow in ./updater.ts
+// once the flag is on; that file is untouched and keeps working while the
+// flag is off.
+import { getVersion } from "@tauri-apps/api/app";
+import { getCurrentWindow } from "@tauri-apps/api/window";
+import {
+  createProcessCheckGate,
+  createTauriUpdaterAdapter,
+  createUpdateController,
+  definePickforgeUpdaterElement,
+  type UpdateAdapter,
+  type UpdateController,
+  type UpdateDialogMetadata,
+  type UpdateEligibility,
+} from "@pickforge/tauri-updater";
+import { desktopApiAvailable } from "./api";
+
+export const MAIN_WINDOW_LABEL = "main";
+
+/** The subset of the Tauri `Window` API eligibility needs, so tests can
+ * inject a fake instead of a real webview window. */
+export interface EligibilityWindow {
+  label: string;
+  isVisible(): Promise<boolean>;
+  isFocused(): Promise<boolean>;
+  onFocusChanged(handler: (event: { payload: boolean }) => void): Promise<() => void>;
+}
+
+/** The DOM surface `mountUpdateDialog` needs from a `<pickforge-update-dialog>`
+ * element, so callers don't have to import the package's element class. */
+export interface UpdateDialogHost {
+  metadata: UpdateDialogMetadata;
+  controller: UpdateController | undefined;
+}
+
+/**
+ * Resolves eligible only for the packaged app's main window once it is both
+ * visible AND focused, per the design contract. The floating capsule
+ * (`label !== "main"`) never resolves true from here. A hidden or unfocused
+ * main window (tray/login-start) waits: every focus-changed event re-queries
+ * both `isVisible()` and `isFocused()` rather than trusting the event payload
+ * alone, and once the listener is registered its current state is re-checked
+ * once more so a window that became visible+focused during that registration
+ * gap can't hang forever waiting for a focus event that already happened.
+ * This mirrors the pre-existing `checkForUpdatesWhenVisible` deferral in
+ * ./updater.ts, strengthened with the focus check.
+ */
+export function createMainWindowEligibility(
+  win: EligibilityWindow,
+  packaged: boolean,
+): UpdateEligibility {
+  return {
+    async whenEligible() {
+      if (!packaged || win.label !== MAIN_WINDOW_LABEL) {
+        return false;
+      }
+
+      const currentlyEligible = async () => {
+        const [visible, focused] = await Promise.all([
+          win.isVisible().catch(() => false),
+          win.isFocused().catch(() => false),
+        ]);
+        return visible && focused;
+      };
+
+      if (await currentlyEligible()) {
+        return true;
+      }
+
+      return new Promise<boolean>((resolve) => {
+        let settled = false;
+        let unlisten: (() => void) | undefined;
+
+        const finish = (value: boolean) => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          unlisten?.();
+          resolve(value);
+        };
+
+        void win
+          .onFocusChanged(({ payload: focused }) => {
+            if (!focused) {
+              return;
+            }
+            void currentlyEligible().then((eligible) => {
+              if (eligible) {
+                finish(true);
+              }
+            });
+          })
+          .then((fn) => {
+            unlisten = fn;
+            // The window may have become visible and focused while the
+            // listener was being registered; re-check once so that gap
+            // can't leave whenEligible() hanging past an already-happened
+            // focus.
+            void currentlyEligible().then((eligible) => {
+              if (eligible) {
+                finish(true);
+              }
+            });
+          })
+          .catch(() => finish(false));
+      });
+    },
+  };
+}
+
+async function createAdapter(): Promise<UpdateAdapter> {
+  const [{ check }, { relaunch }] = await Promise.all([
+    import("@tauri-apps/plugin-updater"),
+    import("@tauri-apps/plugin-process"),
+  ]);
+  return createTauriUpdaterAdapter({ check, relaunch });
+}
+
+let controllerPromise: Promise<UpdateController> | undefined;
+
+/** One controller for the process; its process-check gate enforces a
+ * single update check per process even if this is somehow called twice. */
+function getUpdateController(packaged: boolean): Promise<UpdateController> {
+  controllerPromise ??= (async () => {
+    const adapter = await createAdapter();
+    const eligibility = createMainWindowEligibility(getCurrentWindow(), packaged);
+    return createUpdateController({ adapter, eligibility, gate: createProcessCheckGate() });
+  })();
+  return controllerPromise;
+}
+
+/**
+ * Mounts the shared update dialog on `host` and starts the single
+ * per-process check. No-ops in dev builds and outside Tauri (browser
+ * preview), matching the legacy flow's packaged-build-only behavior.
+ * Startup check failures are swallowed by the controller (silent,
+ * non-blocking); anything else that goes wrong while wiring up is logged
+ * and otherwise ignored so it can never block app startup.
+ */
+export function mountUpdateDialog(host: UpdateDialogHost): void {
+  const packaged = !import.meta.env.DEV && desktopApiAvailable();
+  if (!packaged) {
+    return;
+  }
+
+  definePickforgeUpdaterElement();
+
+  void (async () => {
+    try {
+      const controller = await getUpdateController(packaged);
+      host.metadata = {
+        productName: "PickGauge",
+        currentVersion: await getVersion().catch(() => "—"),
+        productMark: "PG",
+      };
+      host.controller = controller;
+      await controller.start();
+    } catch (error) {
+      console.error("PickGauge update dialog setup failed", error);
+    }
+  })();
+}
diff --git a/src/lib/updateDialogFixture.ts b/src/lib/updateDialogFixture.ts
new file mode 100644
index 0000000..1cc18e0
--- /dev/null
+++ b/src/lib/updateDialogFixture.ts
@@ -0,0 +1,75 @@
+// Dev-only visual fixture for the shared update dialog. PickGauge has no
+// visual-regression/screenshot-baseline harness (see scripts/
+// validate-browser-preview.mjs — functional Playwright assertions, not
+// pixel baselines), so this route stands in for one: `bun run dev` then
+// open `?updateDialogFixture=available` or `?updateDialogFixture=downloading`
+// to inspect the dialog with deterministic, injected state. Resize the
+// window to PickGauge's normal (1000x700) and minimum (820x580) sizes to
+// check both. Never reachable in a production build — `import.meta.env.DEV`
+// is statically eliminated, so this module and its @pickforge/tauri-updater
+// imports are tree-shaken out entirely.
+import {
+  createEligibility,
+  createProcessCheckGate,
+  createUpdateController,
+  definePickforgeUpdaterElement,
+  type UpdateAdapter,
+  type UpdateDialogMetadata,
+} from "@pickforge/tauri-updater";
+import type { UpdateDialogHost } from "./updateDialog";
+
+const FIXTURE_UPDATE = {
+  version: "0.3.0",
+  notes: "Faster refresh polling\nFixed a tray icon flicker on Linux\nSmaller install size",
+};
+
+function fixtureAdapter(scenario: string): UpdateAdapter {
+  return {
+    async check() {
+      return FIXTURE_UPDATE;
+    },
+    async downloadAndInstall(onEvent) {
+      onEvent({ type: "started", contentLength: 100 });
+      if (scenario !== "downloading") {
+        onEvent({ type: "progress", chunkLength: 100 });
+        onEvent({ type: "finished" });
+        return;
+      }
+      // Report some progress, then hang forever so "downloading" is a
+      // stable, screenshot-able state instead of racing to "restarting".
+      onEvent({ type: "progress", chunkLength: 42 });
+      await new Promise<void>(() => {});
+    },
+    async relaunch() {},
+  };
+}
+
+const FIXTURE_METADATA: UpdateDialogMetadata = {
+  productName: "PickGauge",
+  currentVersion: "0.2.0",
+  productMark: "PG",
+};
+
+export async function mountUpdateDialogFixture(
+  target: HTMLElement,
+  scenario: string,
+): Promise<void> {
+  target.replaceChildren();
+  definePickforgeUpdaterElement();
+  const element = document.createElement("pickforge-update-dialog") as unknown as UpdateDialogHost &
+    HTMLElement;
+  target.append(element);
+
+  const controller = createUpdateController({
+    adapter: fixtureAdapter(scenario),
+    eligibility: createEligibility({ packaged: true, mainWindow: true, visible: true, focused: true }),
+    gate: createProcessCheckGate(),
+  });
+  element.metadata = FIXTURE_METADATA;
+  element.controller = controller;
+  await controller.start();
+
+  if (scenario === "downloading") {
+    void controller.install();
+  }
+}
diff --git a/src/lib/updateRouting.test.ts b/src/lib/updateRouting.test.ts
new file mode 100644
index 0000000..f040121
--- /dev/null
+++ b/src/lib/updateRouting.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { shouldMountSharedUpdateDialog, shouldRunLegacyUpdateCheck } from "./updateRouting";
+
+describe("update flow routing (no-double-prompt guarantee)", () => {
+  it("runs only the legacy check on the main window while the flag is off", () => {
+    expect(shouldRunLegacyUpdateCheck("main", false)).toBe(true);
+    expect(shouldMountSharedUpdateDialog(false)).toBe(false);
+  });
+
+  it("runs only the shared dialog once the flag is on", () => {
+    expect(shouldRunLegacyUpdateCheck("main", true)).toBe(false);
+    expect(shouldMountSharedUpdateDialog(true)).toBe(true);
+  });
+
+  it("never runs the legacy check outside the main window, flag on or off", () => {
+    expect(shouldRunLegacyUpdateCheck("float", false)).toBe(false);
+    expect(shouldRunLegacyUpdateCheck("float", true)).toBe(false);
+  });
+});
diff --git a/src/lib/updateRouting.ts b/src/lib/updateRouting.ts
new file mode 100644
index 0000000..d003883
--- /dev/null
+++ b/src/lib/updateRouting.ts
@@ -0,0 +1,19 @@
+// Single source of truth for which update flow may run where, so the legacy
+// `window.confirm` updater (./updater.ts, driven from main.ts) and the shared
+// dialog (./updateDialog.ts, mounted from App.svelte) can never both prompt
+// for the same window. Both derive from the same `studioUpdateDialog` flag
+// value (see ./flags.ts) through these two functions instead of duplicating
+// the condition inline in each call site.
+
+/** True only for the main window while the flag is off — the legacy
+ * `checkForUpdatesWhenVisible` flow. */
+export function shouldRunLegacyUpdateCheck(windowLabel: string, studioDialogEnabled: boolean): boolean {
+  return windowLabel === "main" && !studioDialogEnabled;
+}
+
+/** True once the flag is on — App.svelte (the main-window component; the
+ * floating capsule never imports the dialog module at all) mounts the shared
+ * controller only when this is true. */
+export function shouldMountSharedUpdateDialog(studioDialogEnabled: boolean): boolean {
+  return studioDialogEnabled;
+}
diff --git a/src/main.ts b/src/main.ts
index a5d5dba..792aab3 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -3,8 +3,10 @@ import { mount } from "svelte";
 import App from "./App.svelte";
 import Float from "./Float.svelte";
 import { api, desktopApiAvailable, EVENT_SETTINGS } from "./lib/api";
+import { flagEnabled } from "./lib/flags";
 import { initTheme, setTheme, type ThemeSetting } from "./lib/theme";
 import { checkForUpdatesWhenVisible } from "./lib/updater";
+import { shouldRunLegacyUpdateCheck } from "./lib/updateRouting";
 import type { AppConfig } from "./lib/usage";
 import "./app.css";
 
@@ -14,6 +16,24 @@ if (!target) {
   throw new Error("App root element was not found");
 }
 
+// Dev-only visual fixture for the shared update dialog (see
+// ./lib/updateDialogFixture.ts) — `import.meta.env.DEV` is statically
+// eliminated, so none of this (including the fixture module's
+// @pickforge/tauri-updater imports) reaches a production build.
+const fixtureScenario = import.meta.env.DEV
+  ? new URLSearchParams(window.location.search).get("updateDialogFixture")
+  : null;
+
+let app: ReturnType<typeof mount> | undefined;
+
+if (fixtureScenario) {
+  void import("./lib/updateDialogFixture").then(({ mountUpdateDialogFixture }) =>
+    mountUpdateDialogFixture(target, fixtureScenario),
+  );
+} else {
+  app = mountApp();
+}
+
 function currentWindowLabel() {
   const internals = (
     window as Window & {
@@ -29,27 +49,36 @@ function currentWindowLabel() {
   return new URLSearchParams(window.location.search).get("window") ?? "main";
 }
 
-const windowLabel = currentWindowLabel();
-const component = windowLabel === "float" ? Float : App;
+function mountApp() {
+  const windowLabel = currentWindowLabel();
+  const component = windowLabel === "float" ? Float : App;
 
-if (component === Float) {
-  document.documentElement.classList.add("is-float");
-  document.body.classList.add("float-host");
-}
+  if (component === Float) {
+    document.documentElement.classList.add("is-float");
+    document.body.classList.add("float-host");
+  }
 
-if (desktopApiAvailable()) {
-  api
-    .getAppConfig()
-    .then((config) => initTheme(config.ui.theme as ThemeSetting))
-    .catch(() => initTheme("system"));
-  void listen<AppConfig>(EVENT_SETTINGS, (event) => {
-    void setTheme(event.payload.ui.theme as ThemeSetting);
-  });
-  if (windowLabel === "main") {
-    void checkForUpdatesWhenVisible();
+  if (desktopApiAvailable()) {
+    api
+      .getAppConfig()
+      .then((config) => initTheme(config.ui.theme as ThemeSetting))
+      .catch(() => initTheme("system"));
+    void listen<AppConfig>(EVENT_SETTINGS, (event) => {
+      void setTheme(event.payload.ui.theme as ThemeSetting);
+    });
+    // App.svelte itself mounts the shared update dialog when
+    // `studioUpdateDialog` is on (see its `showUpdateDialog` check, driven by
+    // the same ./lib/updateRouting predicates); running the legacy
+    // `window.confirm` flow here too would double-prompt, so it only runs
+    // while the flag is off.
+    if (shouldRunLegacyUpdateCheck(windowLabel, flagEnabled("studioUpdateDialog"))) {
+      void checkForUpdatesWhenVisible();
+    }
+  } else {
+    initTheme("system");
   }
-} else {
-  initTheme("system");
+
+  return mount(component, { target: target! });
 }
 
-export default mount(component, { target });
+export default app;