feat(hub): add iframe navigation recovery controls

Author: dvcolomban

docs/content/8.references/6.hub-api.md

@@ -137,7 +137,7 @@ The built-in variants of the open dock union (`DevframeDockEntryRegistry`, `@dev
 
 | Type | The hub UI provider renders |
 |---|---|
-| `iframe` | the entry's `url` in a kept-alive iframe (per `frameId` when shared); honor `subTabs` soft nav |
+| `iframe` | the entry's `url` in a kept-alive iframe (per `frameId` when shared); honor `subTabs` soft nav; force the existing address bar with `showAddressBar`; override Back, Reload, and Open externally visibility with `controls.back`, `controls.reload`, and `controls.openExternal` |
 | `action` | a dock-rail button; activating runs its client script |
 | `custom-render` | a container its client script mounts into |
 | `launcher` | a launch call-to-action reflecting `launcher.status` |

packages/hub-ui/src/client/components/views/ViewIframe.vue

@@ -20,7 +20,7 @@ const props = defineProps<{
 
 const settings = useSettings(props.context)
 const isEdgeMode = computed(() => props.context.panel.store.mode === 'edge')
-const showAddressBar = computed(() => settings.value.showIframeAddressBar)
+const showAddressBar = computed(() => settings.value.showIframeAddressBar || props.entry.showAddressBar === true)
 
 const ADDRESS_BAR_HEIGHT = 40
 
@@ -77,13 +77,15 @@ const currentPageOrigin = computed(() => {
 // Check if iframe URL is cross-origin
 const isCrossOrigin = computed(() => {
   try {
-    const url = new URL(currentUrl.value)
-    return url.origin !== currentPageOrigin.value
+    return new URL(currentUrl.value).origin !== currentPageOrigin.value
   }
   catch {
     return true // Assume cross-origin if URL parsing fails
   }
 })
+const showBack = computed(() => props.entry.controls?.back ?? !isCrossOrigin.value)
+const showReload = computed(() => props.entry.controls?.reload ?? !isCrossOrigin.value)
+const showOpenExternal = computed(() => props.entry.controls?.openExternal ?? false)
 
 // Display URL - hides host if same as current page. The remote connection
 // descriptor is stripped so its auth token can't be read (or copied) out of the
@@ -189,10 +191,20 @@ function refresh() {
 
   assetsError.value = null
   isIframeLoading.value = true
-  // Reload by reassigning the src
   const src = iframe.src
   iframe.src = ''
   iframe.src = src
+  currentUrl.value = src
+  editingUrl.value = src
+}
+
+function openExternally() {
+  try {
+    const url = new URL(stripRemoteConnectionFromUrl(currentUrl.value))
+    if (url.protocol === 'http:' || url.protocol === 'https:')
+      window.open(url.href, '_blank', 'noopener,noreferrer')
+  }
+  catch {}
 }
 
 let onIframeLoad: (() => void) | undefined
@@ -322,40 +334,37 @@ onUnmounted(() => {
   <div class="w-full h-full flex flex-col">
     <div
       v-if="showAddressBar"
-      class="flex-none px-2 w-full flex items-center gap-1 border-base border-b"
+      class="flex-none px-2 w-full flex items-center gap-1 color-base border-base border-b"
       :style="{ height: `${ADDRESS_BAR_HEIGHT}px` }"
     >
-      <!-- Navigation buttons (hidden for cross-origin) -->
-      <template v-if="!isCrossOrigin">
-        <!-- Back button -->
-        <button
-          class="w-7 h-7 flex items-center justify-center rounded hover:bg-gray/15 transition-colors shrink-0"
-          title="Back"
-          @click="goBack"
-        >
-          <div class="i-ph-caret-left op60 w-4.5 h-4.5" />
-        </button>
-
-        <!-- Refresh button -->
-        <button
-          class="w-7 h-7 flex items-center justify-center rounded hover:bg-gray/15 transition-colors shrink-0"
-          title="Refresh"
-          @click="refresh"
-        >
-          <div class="i-ph-arrow-clockwise op60 w-4.5 h-4.5" />
-        </button>
-      </template>
+      <button
+        v-if="showBack"
+        class="w-7 h-7 flex items-center justify-center rounded hover:bg-gray/15 transition-colors shrink-0"
+        title="Back"
+        @click="goBack"
+      >
+        <div class="i-ph-caret-left op60 w-4.5 h-4.5" />
+      </button>
 
       <!-- Cross-origin badge -->
       <div
-        v-else
+        v-if="isCrossOrigin"
         class="flex items-center gap-1 px2 py1 rounded text-xs bg-amber/10 text-amber border border-amber/20 shrink-0"
-        title="Cross-origin iframe - navigation controls unavailable"
+        title="Cross-origin iframe"
       >
         <div class="i-ph-globe text-sm" />
         <span>Cross-Origin</span>
       </div>
 
+      <button
+        v-if="showReload"
+        class="w-7 h-7 flex items-center justify-center rounded hover:bg-gray/15 transition-colors shrink-0"
+        title="Reload"
+        @click="refresh"
+      >
+        <div class="i-ph-arrow-clockwise op60 w-4.5 h-4.5" />
+      </button>
+
       <!-- URL input -->
       <div class="flex-1 flex items-center h-7 px-2.5 rounded bg-gray/5 border border-transparent hover:border-gray/10 focus-within:border-gray/15 transition-colors">
         <input
@@ -376,6 +385,15 @@ onUnmounted(() => {
           class="i-ph-circle-notch text-sm op40 ml-2 shrink-0 animate-spin"
         />
       </div>
+
+      <button
+        v-if="showOpenExternal"
+        class="w-7 h-7 flex items-center justify-center rounded hover:bg-gray/15 transition-colors shrink-0"
+        title="Open externally"
+        @click="openExternally"
+      >
+        <div class="i-ph-arrow-square-out-duotone op60 w-4.5 h-4.5" />
+      </button>
     </div>
     <div
       ref="viewFrame"

packages/hub-ui/src/client/components/views/ViewIframeLoading.vue

@@ -1,12 +1,10 @@
 <script setup lang="ts">
-// Placeholder shown while an iframe view loads its content. A blank iframe
-// paints white during load, so this is only visible once the pane steps aside
-// (`pane.hide()` in `ViewIframe`) — the same layering trick `ViewAssetsError`
-// relies on. It covers the initial load and any hard navigation/refresh.
+// Placeholder shown while an iframe view loads its content. The pane steps
+// aside while loading so this inherits the viewer's configured background.
 </script>
 
 <template>
-  <div class="devframes-view-iframe-loading absolute inset-0 flex flex-col items-center justify-center gap-2 bg-base">
+  <div class="devframes-view-iframe-loading absolute inset-0 flex flex-col items-center justify-center gap-2">
     <div class="i-ph:circle-notch-duotone animate-spin text-3xl color-faint" />
     <div class="text-sm color-muted">
       Loading…

packages/hub/src/types/docks.ts

@@ -203,6 +203,17 @@ declare module 'devframe/types' {
 export interface DevframeViewIframe extends DevframeDockEntryBase {
   type: 'iframe'
   url: string
+  /** Show the iframe address bar regardless of the user's global setting. */
+  showAddressBar?: boolean
+  /** Optional address-bar controls. Omitted values retain the existing origin-based behavior. */
+  controls?: {
+    /** Override Back visibility. Cross-origin history access may still be blocked by the browser. */
+    back?: boolean
+    /** Override Reload visibility. */
+    reload?: boolean
+    /** Override the built-in action that opens the displayed HTTP(S) URL in a new tab. */
+    openExternal?: boolean
+  }
   /**
    * The id of the iframe, if multiple tabs is assigned with the same id, the iframe will be shared.
    *

tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts

@@ -293,6 +293,12 @@ export interface DevframeViewGroup extends DevframeDockEntryBase {
 export interface DevframeViewIframe extends DevframeDockEntryBase {
   type: 'iframe';
   url: string;
+  showAddressBar?: boolean;
+  controls?: {
+    back?: boolean;
+    reload?: boolean;
+    openExternal?: boolean;
+  };
   frameId?: string;
   clientScript?: ClientScriptEntry;
   navTarget?: NavTarget;