@forgeax/app-shell 0.12.0 → 0.14.0

package/dist/window.d.ts

@@ -52,8 +52,44 @@ interface CreateBrowserWindowManagerOptions {
     readonly host?: BrowserWindowHost;
     readonly closePollIntervalMs?: number;
 }
+/** Product-neutral handle implemented by event-driven native window adapters. */
+interface ExternalWindowHandle {
+    show(): void | Promise<void>;
+    focus(): void | Promise<void>;
+    close(): void | Promise<void>;
+}
+interface ExternalWindowLifecycle {
+    created(): void;
+    error(): void;
+    destroyed(): void;
+}
+/** Adapter seam: products retain native API loading and concrete create policy. */
+interface ExternalWindowHost {
+    getByLabel(label: string): Promise<ExternalWindowHandle | null>;
+    create(label: string, surface: SurfaceDescriptor, options: DetachWindowOptions | undefined, lifecycle: ExternalWindowLifecycle): Promise<ExternalWindowHandle>;
+}
+interface CreateExternalWindowManagerOptions {
+    readonly canDetach: () => boolean;
+    readonly loadHost: () => Promise<ExternalWindowHost | undefined>;
+    readonly createdTimeoutMs?: number;
+}
+interface OpenPanelWindowOptions {
+    readonly detachSurface: (surface: SurfaceDescriptor, options: Required<Pick<DetachWindowOptions, 'title' | 'width' | 'height'>> & Pick<DetachWindowOptions, 'x' | 'y'>) => Promise<boolean>;
+    readonly position?: Readonly<Pick<DetachWindowOptions, 'x' | 'y'>>;
+    readonly closeDockPanel?: () => void;
+}
+interface PanelWindowingController {
+    openPanelWindow(panelId: string, capability: DetachedWindowCapability | undefined, options: OpenPanelWindowOptions): Promise<boolean>;
+    panelForClosedSurface(surface: SurfaceDescriptor): string | undefined;
+}
+declare function canOpenPanelWindow(capability: DetachedWindowCapability | undefined, carrierAvailable: boolean): capability is DetachedWindowCapability;
+declare function shouldShowDetachedPlaceholder(floatingSurfaces: Readonly<Record<string, true>>, surface: SurfaceDescriptor): boolean;
+/** Product-neutral transaction joining a dock placement to a detached carrier. */
+declare function createPanelWindowingController(): PanelWindowingController;
 /** Product-neutral browser popup carrier with injected surface URL policy. */
 declare function createBrowserWindowManager(options: CreateBrowserWindowManagerOptions): WindowManager;
+/** Event-driven external-window lifecycle with all native policy injected. */
+declare function createExternalWindowManager(options: CreateExternalWindowManagerOptions): WindowManager;
 /** Stable identity shared by keep-alive registries and physical carriers. */
 declare function surfaceKey(surface: SurfaceDescriptor): string;
 /** Deterministic, injective and carrier-safe label for the complete identity. */
@@ -63,4 +99,4 @@ declare function encodeSurfaceQuery(surface: SurfaceDescriptor): string;
 /** Decode structural identity, or null for a normal shell/invalid entry. */
 declare function decodeSurfaceFromLocation(search?: string): SurfaceDescriptor | null;
 
-export { type BrowserPopupWindow, type BrowserWindowHost, type CreateBrowserWindowManagerOptions, type DetachWindowOptions, type DetachedWindowCapability, type DetachedWindowTarget, type SurfaceDescriptor, type SurfaceKind, type SurfacePane, type WindowManager, createBrowserWindowManager, decodeSurfaceFromLocation, encodeSurfaceQuery, surfaceKey, surfaceWindowLabel };
+export { type BrowserPopupWindow, type BrowserWindowHost, type CreateBrowserWindowManagerOptions, type CreateExternalWindowManagerOptions, type DetachWindowOptions, type DetachedWindowCapability, type DetachedWindowTarget, type ExternalWindowHandle, type ExternalWindowHost, type ExternalWindowLifecycle, type OpenPanelWindowOptions, type PanelWindowingController, type SurfaceDescriptor, type SurfaceKind, type SurfacePane, type WindowManager, canOpenPanelWindow, createBrowserWindowManager, createExternalWindowManager, createPanelWindowingController, decodeSurfaceFromLocation, encodeSurfaceQuery, shouldShowDetachedPlaceholder, surfaceKey, surfaceWindowLabel };

package/dist/window.js

@@ -1,4 +1,73 @@
 // src/window.ts
+function canOpenPanelWindow(capability, carrierAvailable) {
+  return capability !== void 0 && carrierAvailable;
+}
+function shouldShowDetachedPlaceholder(floatingSurfaces, surface) {
+  return floatingSurfaces[surfaceKey(surface)] === true;
+}
+function createPanelWindowingController() {
+  const detachedPanels = /* @__PURE__ */ new Map();
+  return {
+    async openPanelWindow(panelId, capability, options) {
+      if (!capability) return false;
+      let target;
+      try {
+        target = capability.createTarget();
+      } catch {
+        return false;
+      }
+      const key = surfaceKey(target.surface);
+      const closesPlacement = target.dockBehavior === "close";
+      let reservation;
+      if (closesPlacement) {
+        if (!options.closeDockPanel || detachedPanels.has(key)) return false;
+        reservation = { panelId, state: "pending" };
+        detachedPanels.set(key, reservation);
+      }
+      let opened;
+      try {
+        opened = await options.detachSurface(target.surface, {
+          title: target.title,
+          width: target.width,
+          height: target.height,
+          ...options.position
+        });
+      } catch {
+        if (reservation && detachedPanels.get(key) === reservation) detachedPanels.delete(key);
+        return false;
+      }
+      if (!opened) {
+        if (reservation && detachedPanels.get(key) === reservation) detachedPanels.delete(key);
+        return false;
+      }
+      if (closesPlacement) {
+        if (detachedPanels.get(key) !== reservation) return false;
+        try {
+          options.closeDockPanel();
+        } catch {
+          if (detachedPanels.get(key) === reservation) detachedPanels.delete(key);
+          return false;
+        }
+        reservation.state = "leased";
+      }
+      return true;
+    },
+    panelForClosedSurface(surface) {
+      const key = surfaceKey(surface);
+      const lease = detachedPanels.get(key);
+      if (lease?.state === "pending") {
+        detachedPanels.delete(key);
+        return void 0;
+      }
+      if (lease?.state === "leased") {
+        queueMicrotask(() => {
+          if (detachedPanels.get(key) === lease) detachedPanels.delete(key);
+        });
+      }
+      return lease?.state === "leased" ? lease.panelId : void 0;
+    }
+  };
+}
 function currentBrowserHost() {
   if (typeof window === "undefined" || typeof window.open !== "function") return void 0;
   return {
@@ -75,6 +144,70 @@ function createBrowserWindowManager(options) {
     }
   };
 }
+function createExternalWindowManager(options) {
+  const closeListeners = /* @__PURE__ */ new Set();
+  const notifyClosed = (surface) => {
+    for (const listener of closeListeners) {
+      try {
+        listener(surface);
+      } catch {
+      }
+    }
+  };
+  return {
+    canDetach: options.canDetach,
+    async openSurfaceWindow(surface, detachOptions) {
+      const host = await options.loadHost();
+      if (!host) return false;
+      const label = surfaceWindowLabel(surface);
+      const existing = await host.getByLabel(label);
+      if (existing) {
+        try {
+          await existing.show();
+          await existing.focus();
+          return true;
+        } catch {
+        }
+      }
+      return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          resolve(result);
+        };
+        const timeout = setTimeout(() => finish(true), options.createdTimeoutMs ?? 2e3);
+        void host.create(label, surface, detachOptions, {
+          created: () => finish(true),
+          error: () => finish(false),
+          destroyed: () => notifyClosed(surface)
+        }).catch(() => finish(false));
+      });
+    },
+    async closeSurfaceWindow(surface) {
+      const host = await options.loadHost();
+      if (!host) return;
+      const existing = await host.getByLabel(surfaceWindowLabel(surface));
+      if (!existing) return;
+      try {
+        await existing.close();
+      } catch {
+      }
+    },
+    async isSurfaceWindowOpen(surface) {
+      const host = await options.loadHost();
+      if (!host) return false;
+      return await host.getByLabel(surfaceWindowLabel(surface)) !== null;
+    },
+    onSurfaceWindowClosed(listener) {
+      closeListeners.add(listener);
+      return () => {
+        closeListeners.delete(listener);
+      };
+    }
+  };
+}
 function surfaceKey(surface) {
   const id = surface.id.includes(":") || surface.id.startsWith("~") ? `~${encodeURIComponent(surface.id)}` : surface.id;
   const pane = surface.pane ? `:${surface.pane}` : "";
@@ -124,9 +257,13 @@ function decodeSurfaceFromLocation(search = typeof window !== "undefined" ? wind
   };
 }
 export {
+  canOpenPanelWindow,
   createBrowserWindowManager,
+  createExternalWindowManager,
+  createPanelWindowingController,
   decodeSurfaceFromLocation,
   encodeSurfaceQuery,
+  shouldShowDetachedPlaceholder,
   surfaceKey,
   surfaceWindowLabel
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/app-shell",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Generic Dock, Panel, Window, and Slot composition primitives",
   "license": "Apache-2.0",
   "type": "module",