gesso-framework 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # gesso-framework
 
+## 0.6.5
+
+### Patch Changes
+
+- e93e0ee: A `Link` can now name an in-app destination with `to`, and a Cmd-click opens it somewhere new, the way a browser treats an anchor. `to` takes one of the application's own urls (`/epic/BUD-12?story=BUD-13`) or a `RouteTarget` from `to(route, params)`. A plain click, Enter or Space runs `onPress` and then navigates the router in place. A click with Command or Control held (either one, on any platform), a middle click, or Cmd-Enter / Ctrl-Enter runs `onPress` and then asks the shell to open the app at that url somewhere new, leaving the current screen where it is. An `href` link is unchanged: it opens through `openUrl` however it is clicked. When a link has both, `to` wins. `Breadcrumb` items take the same `to`.
+
+  The request is the new `ShellService.openRoute(url)`, and what "somewhere new" means is the shell's decision. `createApp` and `GessoApp` take an `onOpenRoute(url)` for a host with its own idea of a new tab, such as an app inside Jira opening one through Forge's `router.open`. Without one, a browser shell opens a tab at the app's own address for that url: the path on the same origin in `path` mode, the same page with the fragment set in `hash` mode. In `memory` mode there is no address, so the link is followed in place. A handed-in `ShellHistory` can answer the new optional `href(url)` to give the address itself; without it, such a link is also followed in place.
+
+  In `gesso-electrobun`, the view bridge has `openRoute(url)` to pass as `onOpenRoute`, and `createDesktopApp` answers it by opening a new window of the application at that route: `openWindow({ route })`, and an `onOpenRoute(url, window)` option to do something else. A window learns its route from the page it loads: `open` reads `window.route`, `withWindowRoute` puts it in the view url's fragment, and `windowRoute()` reads it back as the window's starting url. An `open` that ignores it keeps working. The Electrobun template does all three.
+
+- gesso-core@0.6.5
+
+## 0.6.4
+
+### Patch Changes
+
+- 2f6a858: The `history` option now also takes a ready-made `ShellHistory`, for an app embedded in a page whose address bar belongs to its host. An app in an iframe inside another product, such as an Atlassian Forge Custom UI app in Jira, can reach the host's address only through a history object the host hands out. Adapt that object to `ShellHistory` and pass it to `createApp`, `createSyncApp(...).useHistory` or `GessoApp` in place of `{ mode }`, and the router reads its starting url from it, pushes and replaces through it, and follows the changes it reports. A history passed in stays the caller's: disposing the app stops listening to it but does not dispose it, so it survives a remount. Options work exactly as before.
+- gesso-core@0.6.4
+
 ## 0.6.3
 
 ### Patch Changes

package/dist/{index-DWQA6g_M.d.ts → index-B8PU7Cf0.d.ts}

@@ -1664,6 +1664,9 @@ type ShellRequest = {
 } | {
   type: 'openUrl';
   url: string;
+} | {
+  type: 'openRoute';
+  url: string;
 } | {
   type: 'redirect';
   url: string;
@@ -1949,6 +1952,30 @@ declare class ShellService {
   settleClipboard(id: number, copied: boolean): void;
   /** Opens a URL in the user's browser, in a new tab or window. */
   openUrl(url: string): void;
+  /**
+   * Opens this application at one of its own urls, somewhere new: what
+   * a Cmd-click or a Ctrl-click on an in-app link asks for.
+   *
+   * Not `openUrl`, because the two urls are different kinds of thing.
+   * `openUrl` takes an address that already means something to the
+   * browser. This takes the router's url, `/epic/BUD-12?story=BUD-13`,
+   * which means something only to this application, and only the
+   * shell knows what address shows the application at it: a path on
+   * the page's origin, a fragment on the page's own address, a tab in
+   * the product the app is embedded in, or a new native window. The
+   * render thread cannot know which, so it names the route and the
+   * shell decides.
+   *
+   * What each shell does, in order: the host's `onOpenRoute` if it gave
+   * one; otherwise a new tab at the address the history gives for the
+   * url (`ShellHistory.href`); otherwise, where there is no address,
+   * which is `memory` mode, the shell follows the url in place, exactly
+   * as `RouterService.navigate` would, rather than doing nothing.
+   *
+   * The current screen does not navigate. Nothing comes back, as with
+   * `openUrl`. With no shell installed the request is dropped.
+   */
+  openRoute(url: string): void;
   /**
    * Replaces the page with `url`, leaving the application.
    *
@@ -4895,6 +4922,16 @@ type RuntimeToShellMessage = {
   type: 'openUrl';
   url: string;
 } |
+/**
+ * Open the app at one of its own urls somewhere new
+ * (ShellService.openRoute). `url` is the router's, not an address:
+ * the shell turns it into one, through its `onOpenRoute` or its
+ * history, or follows it in place when it has neither.
+ */
+{
+  type: 'openRoute';
+  url: string;
+} |
 /**
  * Replace the page with a url, leaving the app (ShellService.redirect).
  * `url` is as the component gave it, relative or not; the shell
@@ -5326,6 +5363,18 @@ interface ShellHistoryOptions {
   /** `memory` mode only: where the app starts. Defaults to `/`. */
   readonly initialUrl?: string;
 }
+/**
+ * A url kept somewhere, which the shell reads, writes and listens to.
+ *
+ * `createShellHistory` makes one from `ShellHistoryOptions`, and that
+ * covers every window the app owns the address of. An app embedded in
+ * a page whose address belongs to something else does not own it: an
+ * Atlassian Forge Custom UI app runs in an iframe inside Jira, and the
+ * only way to Jira's address bar is the history object Forge's bridge
+ * hands out. Such a host implements this interface over whatever it
+ * has, and passes the object as the app's `history` option in place of
+ * options, so the router and the host's address bar stay one url.
+ */
 interface ShellHistory {
   /** The url the window is at now. */
   readonly url: string;
@@ -5333,9 +5382,31 @@ interface ShellHistory {
   replace(url: string): void;
   back(): void;
   forward(): void;
-  /** Reports urls the person produced: back, forward, or a typed address. */
+  /**
+   * Reports urls the person produced: back, forward, or a typed address.
+   *
+   * There is one listener, and a second call replaces the first. An
+   * app that was handed its history and is being taken down relies on
+   * that to stop listening, since disposing a history it did not make
+   * is not its decision.
+   */
   onChange(listener: (url: string) => void): void;
   dispose(): void;
+  /**
+   * The address a new tab would open to show the app at `url`, or null
+   * when this history has none to give.
+   *
+   * Asked when a link is followed somewhere new (`ShellService.openRoute`,
+   * a Cmd-click or a Ctrl-click). The browser modes answer with the
+   * document address that holds `url`, which is what `push` would have
+   * written; `memory` answers null, because a url kept in memory names
+   * no page anything else could load. Optional, because a history an
+   * embedder wrote may have no such answer either, and leaving it out
+   * says exactly that: the shell then follows the link in place. A
+   * host that can open its own kind of tab (Jira's, through Forge's
+   * `router.open`) says so with the shell's `onOpenRoute` instead.
+   */
+  href?(url: string): string | null;
 }
 /**
  * Just the parts of a window this module uses.
@@ -5455,6 +5526,25 @@ interface WorkerAppOptions {
    * reach. `gesso-electrobun`'s bridge is what goes here.
    */
   onOpenUrl?: (url: string) => void;
+  /**
+   * Opens the app at one of its own urls somewhere new
+   * (`ShellService.openRoute`, a Cmd-click or a Ctrl-click on an in-app
+   * `Link`), in place of a new browser tab.
+   *
+   * `url` is the router's, `/epic/BUD-12?story=BUD-13`, not an address.
+   * Without this the shell opens a new tab at the address its history
+   * gives for it (`ShellHistory.href`): the origin and the path in
+   * `path` mode, the page with that fragment in `hash` mode. With no
+   * address to give, in `memory` mode or with a history that has no
+   * `href`, it follows the url in place.
+   *
+   * A host whose idea of a new tab is not the browser's goes here: an
+   * app embedded in another product opens one of that product's tabs
+   * (an Atlassian Forge app, Forge's `router.open`), and a desktop
+   * window asks for another window (`gesso-electrobun`'s bridge,
+   * `openRoute`).
+   */
+  onOpenRoute?: (url: string) => void;
   /**
    * Replaces the page with a url the application asked for
    * (`ShellService.redirect`), in place of `window.location.assign`.
@@ -5570,8 +5660,18 @@ interface WorkerAppOptions {
    * routes, resolves nothing, and could not — a route names a
    * component class, which never leaves the worker. It reports the url
    * the window is at and performs the pushes the worker asks for.
+   *
+   * Or a `ShellHistory` made elsewhere, for a page whose address the
+   * app does not own. An app embedded in another product — an
+   * Atlassian Forge Custom UI app is an iframe inside Jira — reaches
+   * the address bar only through the history object its host hands
+   * out, so it adapts that object to `ShellHistory` and passes it here,
+   * and the router and the host's address stay one url. A history
+   * passed this way is used as it is and survives the app: unmount
+   * stops listening to it but does not dispose it, by the rule
+   * `appLogicWorker` follows, and a remount picks the same one up.
    */
-  history?: ShellHistoryOptions;
+  history?: ShellHistoryOptions | ShellHistory;
 }
 declare class WorkerApp {
   private readonly options;
@@ -5604,6 +5704,8 @@ declare class WorkerApp {
    */
   private scrollability;
   private history;
+  /** True only when the history was made here from options; see `resolveShellHistory`. */
+  private ownsHistory;
   /** True once the render worker has answered `ready` at least once. */
   private ready;
   /** The running `requestAnimationFrame` handle, when ticks are wanted. */
@@ -6026,8 +6128,11 @@ declare class GessoAppBuilder {
   /**
    * How the app's url is kept: `path` (pushState, the default in a
    * browser), `hash`, or `memory`. See `shellHistory`.
+   *
+   * Or a `ShellHistory` made elsewhere, for an app embedded in a page
+   * whose address belongs to its host; see `GessoAppOptions.history`.
    */
-  useHistory(history: ShellHistoryOptions): this;
+  useHistory(history: ShellHistoryOptions | ShellHistory): this;
   /**
    * Pins the rendering backend. Without this the app is on `auto`:
    * WebGPU where the browser has it, Canvas2D elsewhere.
@@ -6152,8 +6257,20 @@ interface GessoAppOptions {
   /**
    * How the app's url is kept: `path` (pushState, the default in a
    * browser), `hash`, or `memory`. See `shellHistory`.
+   *
+   * Or a `ShellHistory` made elsewhere, for a page whose address the
+   * app does not own: an iframe inside another product, where the
+   * host's own history object is the only way to its address bar. It
+   * is used as it is, and left undisposed when the app is disposed,
+   * because it belongs to whoever passed it.
+   */
+  history?: ShellHistoryOptions | ShellHistory;
+  /**
+   * Opens the app at one of its own urls somewhere new
+   * (`ShellService.openRoute`), in place of a new browser tab. The
+   * same option, and the same fallbacks, as `WorkerAppOptions.onOpenRoute`.
    */
-  history?: ShellHistoryOptions;
+  onOpenRoute?: (url: string) => void;
   canvas?: CanvasHost;
   /** The rendering backend; see RendererChoice. Defaults to `auto`. */
   renderer?: RendererChoice;
@@ -6223,6 +6340,7 @@ declare class GessoApp {
   private readonly accessibilityEnabled;
   private readonly adapter;
   private readonly historyOptions;
+  private readonly onOpenRoute;
   private running;
   private resizeObserver;
   private proxy;
@@ -6230,6 +6348,8 @@ declare class GessoApp {
   private audio;
   private mirror;
   private history;
+  /** True only when the history was made here from options; see `resolveShellHistory`. */
+  private ownsHistory;
   private detachVisibility;
   private detachFileDrop;
   /** Pickers and remembered handles, made on the first file request. */
@@ -8319,4 +8439,4 @@ declare class RenderWorkerApp {
 }
 //#endregion
 export { StorageAdapter as $, UiOwnerReport as $n, Resource as $r, FontFaceDeclaration as $t, Presence as A, AudioState as An, Channel as Ar, ActionCause as At, PersistedOptions as B, ShellFileType as Bn, bind as Br, UiTreeSnapshot as Bt, FocusService as C, formatUrl as Cn, pickKeys as Cr, AppLogicEndpoint as Ct, FindService as D, AudioRequest as Dn, findUnplainPath as Dr, ShellHistoryMode as Dt, TextService as E, AudioMetadata as En, createChannelRegistry as Er, ShellHistory as Et, AudioSinkOptions as F, UiDuration as Fn, ControlledOptions as Fr, DevtoolsEvent as Ft, IndexedDbStorage as G, ShellStorageResult as Gn, EachKey as Gr, FrameMetrics as Gt, persisted as H, ShellRequest as Hn, ShowProps as Hr, RuntimeErrorSource as Ht, AudioSinkOutput as I, UiEasingChoice as In, ControlledValue as Ir, DevtoolsRequest as It, OpfsFileHandle as J, observeColorScheme as Jn, debounced as Jr, GessoRuntimeOptions as Jt, IndexedDbStorageOptions as K, ColorScheme as Kn, EachProps as Kr, FramePhaseTimings as Kt, MediaSessionLike as L, ShellFile as Ln, controlled as Lr, FrameEntry as Lt, RouterOutlet as M, AnimateOptions as Mn, Inject as Mr, ChannelErrorEntry as Mt, AudioElementLike as N, AnimationService as Nn, Input as Nr, CommandEntry as Nt, observeMediaQuery as O, AudioSample as On, requirePlainData as Or, ShellHistoryOptions as Ot, AudioSink as P, SpringOptions as Pn, Output as Pr, ConsoleEntry as Pt, MemoryStorage as Q, UiNodeReport as Qn, mutate as Qr, UiFramePhase as Qt, audioClock as R, ShellFileRequest as Rn, ThemeTokenCell as Rr, PatchEntry as Rt, writeClipboard as S, buildPath as Sn, pick as Sr, createApp as St, EditingService as T, AudioAction as Tn, ChannelRegistryHandle as Tr, WorkerAppOptions as Tt, ShellStorage as U, ShellService as Un, show as Ur, RuntimeToShellMessage as Ut, PersistedState as V, ShellRecentFile as Vn, Show as Vr, treeText as Vt, ShellStorageOptions as W, ShellStorageOp as Wn, Each as Wr, ShellToRuntimeMessage as Wt, OpfsStorageOptions as X, NodePathTarget as Xn, MutateOptions as Xr, RuntimeInput as Xt, OpfsStorage as Y, BoundStream as Yn, throttled as Yr, RendererChoice as Yt, OpfsWritable as Z, UiEnvironmentReport as Zn, Mutation as Zr, UI_FRAME_PHASES as Zt, EditingMirrorTarget as _, derive as _i, RouteOptions as _n, createComponent as _r, GessoAppOptions as _t, UiRole as a, select as ai, MediaOptions as an, formatAge as ar, storageReadValue as at, EditingProxy as b, to as bn, isComponentElement as br, WebMcpChoice as bt, UiSemanticsPatch as c, FanOut as ci, RouteMatch as cn, formatStream as cr, UndoableOptions as ct, markNow as d, ComputedCell as di, RouterService as dn, ComponentHost as dr, UndoStackOptions as dt, ResourceOptions as ei, FontFaceLike as en, UiPropOrigin as er, StorageOutcome as et, measureSpan as f, ComputedOptions as fi, RouteState as fn, OverlayLayer as fr, UndoTransaction as ft, renderRoot as g, Equality as gi, RouteGuard as gn, OverlayService as gr, GessoApp as gt, RenderWorkerApp as h, DeriveOptions as hi, RouteDefinition as hn, OverlayRect as hr, shellStorageDenied as ht, UI_SEMANTIC_STATES as i, SelectOptions as ii, FontService as in, describeStream as ir, storageReadFailure as it, PresenceProps as j, AudioStatus as jn, Define as jr, ActionEntry as jt, observeReducedMotion as k, AudioService as kn, ChannelRegistry as kr, createShellHistory as kt, UiSemanticsRecord$1 as l, FanOutOptions as li, RouterHistorySink as ln, printPropValue as lr, undoable as lt, setPerformanceMarks$1 as m, computed as mi, RouteContext as mn, OverlayPlacement as mr, performShellStorage as mt, MARK_PREFIX as n, ResourceStatus as ni, FontFamilyStatus as nn, UiSemanticsReport as nr, classifyStorageError as nt, UiSemanticState as o, FanCell as oi, MediaService as on, formatNodePath as or, UndoShortcutOptions as ot, performanceMarksEnabled as p, ReadSource as pi, OutletProps as pn, OverlayEntry as pr, ShellLocalStore as pt, OpfsDirectory as q, ColorSchemePreference as qn, each as qr, GessoRuntime as qt, UI_ROLES as r, resource as ri, FontHost as rn, UiStreamReport as rr, storageErrorMessage as rt, UiSemanticsMap$1 as s, FanKey as si, RouteAnswer as sn, formatNodeReport as sr, registerUndoShortcuts as st, EditingState$1 as t, ResourceState as ti, FontFamilyDeclaration as tn, UiPropReport as tr, StorageRead as tt, markInstant as u, fanOut as ui, RouterRoutes as un, ComponentHostResolver as ur, UndoStack as ut, SemanticsMirror as v, ServiceRegistry as vi, RouteTarget as vn, ComponentElement as vr, createSyncApp as vt, ScrollService as w, parseUrl as wn, ChannelRegistration as wr, WorkerApp as wt, EditingProxySink as x, RouteParams as xn, structurallyEqual as xr, CreateAppOptions as xt, SemanticsMirrorSink as y, route as yn, FrameworkChild as yr, GessoAppBuilder as yt, FrameService as z, ShellFileResult as zn, themeTokenCell as zr, UiTreeNode as zt };
-//# sourceMappingURL=index-DWQA6g_M.d.ts.map
+//# sourceMappingURL=index-B8PU7Cf0.d.ts.map

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { _ as channel, a as isChannelHostMessage, c as applyPatch, d as ChannelSpec, f as ChannelToken, g as ViewOf, h as CommandsOf, i as isChannelClientMessage, l as applyPatches, m as CommandMap, n as ChannelHostMessage, o as Patch, p as Command, r as ChannelPort, s as PatchPath, t as ChannelClientMessage, u as diffProjection, v as defineChannel, y as viewKeys } from "./ChannelProtocol-ByNoHujM.js";
 import { A as portHandle, C as MessageEndpoint, D as isHubMessage, E as WorkerHandle, F as JsonSchema, I as channelSchema, L as describeChannel, M as workerHandle, N as ChannelSchema, O as isPortErrorMessage, P as CommandSchema, S as APPLICATION_WORKER, T as PortHost, _ as serve, b as ProvidedChannel, g as ServedChannel, j as servePorts, k as isPortHandshake, v as serveChannels, w as PortHandshake, x as provide, y as ChannelSource } from "./ui-U39HjNFA.js";
 import { C as internalState, S as InternalState, _ as ReadableCell, a as ComponentType, b as isOutputTarget, c as isClassComponent, d as bounds, f as EmitArgs, g as OutputTarget, h as OutputCell, i as ComponentProps, l as ChannelReplica, m as InputCell, o as FunctionComponent, p as EmitValue, r as ComponentContext, s as Inputs, t as ClassComponent, u as BoundsCell, v as input, w as Component, x as output, y as into } from "./FunctionComponent-fYMdePtH.js";
-import { $ as StorageAdapter, $n as UiOwnerReport, $r as Resource, $t as FontFaceDeclaration, A as Presence, An as AudioState, Ar as Channel, At as ActionCause, B as PersistedOptions, Bn as ShellFileType, Br as bind, Bt as UiTreeSnapshot, C as FocusService, Cn as formatUrl, Cr as pickKeys, Ct as AppLogicEndpoint, D as FindService, Dn as AudioRequest, Dr as findUnplainPath, Dt as ShellHistoryMode, E as TextService, En as AudioMetadata, Er as createChannelRegistry, Et as ShellHistory, F as AudioSinkOptions, Fn as UiDuration, Fr as ControlledOptions, Ft as DevtoolsEvent, G as IndexedDbStorage, Gn as ShellStorageResult, Gr as EachKey, Gt as FrameMetrics, H as persisted, Hn as ShellRequest, Hr as ShowProps, Ht as RuntimeErrorSource, I as AudioSinkOutput, In as UiEasingChoice, Ir as ControlledValue, It as DevtoolsRequest, J as OpfsFileHandle, Jn as observeColorScheme, Jr as debounced, Jt as GessoRuntimeOptions, K as IndexedDbStorageOptions, Kn as ColorScheme, Kr as EachProps, Kt as FramePhaseTimings, L as MediaSessionLike, Ln as ShellFile, Lr as controlled, Lt as FrameEntry, M as RouterOutlet, Mn as AnimateOptions, Mr as Inject, Mt as ChannelErrorEntry, N as AudioElementLike, Nn as AnimationService, Nr as Input, Nt as CommandEntry, O as observeMediaQuery, On as AudioSample, Or as requirePlainData, Ot as ShellHistoryOptions, P as AudioSink, Pn as SpringOptions, Pr as Output, Pt as ConsoleEntry, Q as MemoryStorage, Qn as UiNodeReport, Qr as mutate, Qt as UiFramePhase, R as audioClock, Rn as ShellFileRequest, Rr as ThemeTokenCell, Rt as PatchEntry, S as writeClipboard, Sn as buildPath, Sr as pick, St as createApp, T as EditingService, Tn as AudioAction, Tr as ChannelRegistryHandle, Tt as WorkerAppOptions, U as ShellStorage, Un as ShellService, Ur as show, Ut as RuntimeToShellMessage, V as PersistedState, Vn as ShellRecentFile, Vr as Show, Vt as treeText, W as ShellStorageOptions, Wn as ShellStorageOp, Wr as Each, Wt as ShellToRuntimeMessage, X as OpfsStorageOptions, Xn as NodePathTarget, Xr as MutateOptions, Xt as RuntimeInput, Y as OpfsStorage, Yn as BoundStream, Yr as throttled, Yt as RendererChoice, Z as OpfsWritable, Zn as UiEnvironmentReport, Zr as Mutation, Zt as UI_FRAME_PHASES, _ as EditingMirrorTarget, _i as derive, _n as RouteOptions, _r as createComponent, _t as GessoAppOptions, a as UiRole, ai as select, an as MediaOptions, ar as formatAge, at as storageReadValue, b as EditingProxy, bn as to, br as isComponentElement, bt as WebMcpChoice, c as UiSemanticsPatch, ci as FanOut, cn as RouteMatch, cr as formatStream, ct as UndoableOptions, d as markNow, di as ComputedCell, dn as RouterService, dr as ComponentHost, dt as UndoStackOptions, ei as ResourceOptions, en as FontFaceLike, er as UiPropOrigin, et as StorageOutcome, f as measureSpan, fi as ComputedOptions, fn as RouteState, fr as OverlayLayer, ft as UndoTransaction, g as renderRoot, gi as Equality, gn as RouteGuard, gr as OverlayService, gt as GessoApp, h as RenderWorkerApp, hi as DeriveOptions, hn as RouteDefinition, hr as OverlayRect, ht as shellStorageDenied, i as UI_SEMANTIC_STATES, ii as SelectOptions, in as FontService, ir as describeStream, it as storageReadFailure, j as PresenceProps, jn as AudioStatus, jr as Define, jt as ActionEntry, k as observeReducedMotion, kn as AudioService, kr as ChannelRegistry, kt as createShellHistory, l as UiSemanticsRecord, li as FanOutOptions, ln as RouterHistorySink, lr as printPropValue, lt as undoable, m as setPerformanceMarks, mi as computed, mn as RouteContext, mr as OverlayPlacement, mt as performShellStorage, n as MARK_PREFIX, ni as ResourceStatus, nn as FontFamilyStatus, nr as UiSemanticsReport, nt as classifyStorageError, o as UiSemanticState, oi as FanCell, on as MediaService, or as formatNodePath, ot as UndoShortcutOptions, p as performanceMarksEnabled, pi as ReadSource, pn as OutletProps, pr as OverlayEntry, pt as ShellLocalStore, q as OpfsDirectory, qn as ColorSchemePreference, qr as each, qt as GessoRuntime, r as UI_ROLES, ri as resource, rn as FontHost, rr as UiStreamReport, rt as storageErrorMessage, s as UiSemanticsMap, si as FanKey, sn as RouteAnswer, sr as formatNodeReport, st as registerUndoShortcuts, t as EditingState, ti as ResourceState, tn as FontFamilyDeclaration, tr as UiPropReport, tt as StorageRead, u as markInstant, ui as fanOut, un as RouterRoutes, ur as ComponentHostResolver, ut as UndoStack, v as SemanticsMirror, vi as ServiceRegistry, vn as RouteTarget, vr as ComponentElement, vt as createSyncApp, w as ScrollService, wn as parseUrl, wr as ChannelRegistration, wt as WorkerApp, x as EditingProxySink, xn as RouteParams, xr as structurallyEqual, xt as CreateAppOptions, y as SemanticsMirrorSink, yn as route, yr as FrameworkChild, yt as GessoAppBuilder, z as FrameService, zn as ShellFileResult, zr as themeTokenCell, zt as UiTreeNode } from "./index-DWQA6g_M.js";
+import { $ as StorageAdapter, $n as UiOwnerReport, $r as Resource, $t as FontFaceDeclaration, A as Presence, An as AudioState, Ar as Channel, At as ActionCause, B as PersistedOptions, Bn as ShellFileType, Br as bind, Bt as UiTreeSnapshot, C as FocusService, Cn as formatUrl, Cr as pickKeys, Ct as AppLogicEndpoint, D as FindService, Dn as AudioRequest, Dr as findUnplainPath, Dt as ShellHistoryMode, E as TextService, En as AudioMetadata, Er as createChannelRegistry, Et as ShellHistory, F as AudioSinkOptions, Fn as UiDuration, Fr as ControlledOptions, Ft as DevtoolsEvent, G as IndexedDbStorage, Gn as ShellStorageResult, Gr as EachKey, Gt as FrameMetrics, H as persisted, Hn as ShellRequest, Hr as ShowProps, Ht as RuntimeErrorSource, I as AudioSinkOutput, In as UiEasingChoice, Ir as ControlledValue, It as DevtoolsRequest, J as OpfsFileHandle, Jn as observeColorScheme, Jr as debounced, Jt as GessoRuntimeOptions, K as IndexedDbStorageOptions, Kn as ColorScheme, Kr as EachProps, Kt as FramePhaseTimings, L as MediaSessionLike, Ln as ShellFile, Lr as controlled, Lt as FrameEntry, M as RouterOutlet, Mn as AnimateOptions, Mr as Inject, Mt as ChannelErrorEntry, N as AudioElementLike, Nn as AnimationService, Nr as Input, Nt as CommandEntry, O as observeMediaQuery, On as AudioSample, Or as requirePlainData, Ot as ShellHistoryOptions, P as AudioSink, Pn as SpringOptions, Pr as Output, Pt as ConsoleEntry, Q as MemoryStorage, Qn as UiNodeReport, Qr as mutate, Qt as UiFramePhase, R as audioClock, Rn as ShellFileRequest, Rr as ThemeTokenCell, Rt as PatchEntry, S as writeClipboard, Sn as buildPath, Sr as pick, St as createApp, T as EditingService, Tn as AudioAction, Tr as ChannelRegistryHandle, Tt as WorkerAppOptions, U as ShellStorage, Un as ShellService, Ur as show, Ut as RuntimeToShellMessage, V as PersistedState, Vn as ShellRecentFile, Vr as Show, Vt as treeText, W as ShellStorageOptions, Wn as ShellStorageOp, Wr as Each, Wt as ShellToRuntimeMessage, X as OpfsStorageOptions, Xn as NodePathTarget, Xr as MutateOptions, Xt as RuntimeInput, Y as OpfsStorage, Yn as BoundStream, Yr as throttled, Yt as RendererChoice, Z as OpfsWritable, Zn as UiEnvironmentReport, Zr as Mutation, Zt as UI_FRAME_PHASES, _ as EditingMirrorTarget, _i as derive, _n as RouteOptions, _r as createComponent, _t as GessoAppOptions, a as UiRole, ai as select, an as MediaOptions, ar as formatAge, at as storageReadValue, b as EditingProxy, bn as to, br as isComponentElement, bt as WebMcpChoice, c as UiSemanticsPatch, ci as FanOut, cn as RouteMatch, cr as formatStream, ct as UndoableOptions, d as markNow, di as ComputedCell, dn as RouterService, dr as ComponentHost, dt as UndoStackOptions, ei as ResourceOptions, en as FontFaceLike, er as UiPropOrigin, et as StorageOutcome, f as measureSpan, fi as ComputedOptions, fn as RouteState, fr as OverlayLayer, ft as UndoTransaction, g as renderRoot, gi as Equality, gn as RouteGuard, gr as OverlayService, gt as GessoApp, h as RenderWorkerApp, hi as DeriveOptions, hn as RouteDefinition, hr as OverlayRect, ht as shellStorageDenied, i as UI_SEMANTIC_STATES, ii as SelectOptions, in as FontService, ir as describeStream, it as storageReadFailure, j as PresenceProps, jn as AudioStatus, jr as Define, jt as ActionEntry, k as observeReducedMotion, kn as AudioService, kr as ChannelRegistry, kt as createShellHistory, l as UiSemanticsRecord, li as FanOutOptions, ln as RouterHistorySink, lr as printPropValue, lt as undoable, m as setPerformanceMarks, mi as computed, mn as RouteContext, mr as OverlayPlacement, mt as performShellStorage, n as MARK_PREFIX, ni as ResourceStatus, nn as FontFamilyStatus, nr as UiSemanticsReport, nt as classifyStorageError, o as UiSemanticState, oi as FanCell, on as MediaService, or as formatNodePath, ot as UndoShortcutOptions, p as performanceMarksEnabled, pi as ReadSource, pn as OutletProps, pr as OverlayEntry, pt as ShellLocalStore, q as OpfsDirectory, qn as ColorSchemePreference, qr as each, qt as GessoRuntime, r as UI_ROLES, ri as resource, rn as FontHost, rr as UiStreamReport, rt as storageErrorMessage, s as UiSemanticsMap, si as FanKey, sn as RouteAnswer, sr as formatNodeReport, st as registerUndoShortcuts, t as EditingState, ti as ResourceState, tn as FontFamilyDeclaration, tr as UiPropReport, tt as StorageRead, u as markInstant, ui as fanOut, un as RouterRoutes, ur as ComponentHostResolver, ut as UndoStack, v as SemanticsMirror, vi as ServiceRegistry, vn as RouteTarget, vr as ComponentElement, vt as createSyncApp, w as ScrollService, wn as parseUrl, wr as ChannelRegistration, wt as WorkerApp, x as EditingProxySink, xn as RouteParams, xr as structurallyEqual, xt as CreateAppOptions, y as SemanticsMirrorSink, yn as route, yr as FrameworkChild, yt as GessoAppBuilder, z as FrameService, zn as ShellFileResult, zr as themeTokenCell, zt as UiTreeNode } from "./index-B8PU7Cf0.js";
 export { APPLICATION_WORKER, type ActionCause, type ActionEntry, type AnimateOptions, AnimationService, type AppLogicEndpoint, type AudioAction, type AudioElementLike, type AudioMetadata, type AudioRequest, type AudioSample, AudioService, AudioSink, type AudioSinkOptions, type AudioSinkOutput, type AudioState, type AudioStatus, type BoundStream, BoundsCell, Channel, type ChannelClientMessage, type ChannelErrorEntry, type ChannelHostMessage, type ChannelPort, type ChannelRegistration, ChannelRegistry, type ChannelRegistryHandle, ChannelReplica, type ChannelSchema, type ChannelSource, type ChannelSpec, type ChannelToken, type ClassComponent, type ColorScheme, type ColorSchemePreference, type Command, type CommandEntry, type CommandMap, type CommandSchema, type CommandsOf, Component, type ComponentContext, type ComponentElement, ComponentHost, ComponentHostResolver, type ComponentProps, type ComponentType, ComputedCell, type ComputedOptions, type ConsoleEntry, type ControlledOptions, type ControlledValue, type CreateAppOptions, Define, type DeriveOptions, type DevtoolsEvent, type DevtoolsRequest, Each, type EachKey, type EachProps, type EditingMirrorTarget, EditingProxy, type EditingProxySink, EditingService, type EditingState, type EmitArgs, type EmitValue, type Equality, FanCell, type FanKey, FanOut, type FanOutOptions, FindService, FocusService, type FontFaceDeclaration, type FontFaceLike, type FontFamilyDeclaration, type FontFamilyStatus, type FontHost, FontService, type FrameEntry, type FrameMetrics, type FramePhaseTimings, FrameService, type FrameworkChild, type FunctionComponent, GessoApp, GessoAppBuilder, type GessoAppOptions, GessoRuntime, type GessoRuntimeOptions, IndexedDbStorage, type IndexedDbStorageOptions, Inject, Input, InputCell, type Inputs, InternalState, type JsonSchema, MARK_PREFIX, type MediaOptions, MediaService, type MediaSessionLike, MemoryStorage, type MessageEndpoint, type MutateOptions, type Mutation, type NodePathTarget, type OpfsDirectory, type OpfsFileHandle, OpfsStorage, type OpfsStorageOptions, type OpfsWritable, type OutletProps, Output, type OutputCell, type OutputTarget, type OverlayEntry, OverlayLayer, type OverlayPlacement, type OverlayRect, OverlayService, type Patch, type PatchEntry, type PatchPath, type PersistedOptions, PersistedState, type PortHandshake, type PortHost, Presence, type PresenceProps, ProvidedChannel, type ReadSource, type ReadableCell, RenderWorkerApp, type RendererChoice, Resource, type ResourceOptions, type ResourceState, type ResourceStatus, type RouteAnswer, type RouteContext, type RouteDefinition, type RouteGuard, type RouteMatch, type RouteOptions, type RouteParams, RouteState, type RouteTarget, type RouterHistorySink, RouterOutlet, type RouterRoutes, RouterService, type RuntimeErrorSource, type RuntimeInput, type RuntimeToShellMessage, ScrollService, type SelectOptions, SemanticsMirror, type SemanticsMirrorSink, type ServedChannel, ServiceRegistry, type ShellFile, type ShellFileRequest, type ShellFileResult, type ShellFileType, type ShellHistory, type ShellHistoryMode, type ShellHistoryOptions, type ShellLocalStore, type ShellRecentFile, type ShellRequest, ShellService, ShellStorage, type ShellStorageOp, type ShellStorageOptions, type ShellStorageResult, type ShellToRuntimeMessage, Show, type ShowProps, type SpringOptions, type StorageAdapter, type StorageOutcome, type StorageRead, TextService, ThemeTokenCell, UI_FRAME_PHASES, UI_ROLES, UI_SEMANTIC_STATES, type UiDuration, type UiEasingChoice, type UiEnvironmentReport, type UiFramePhase, type UiNodeReport, type UiOwnerReport, type UiPropOrigin, type UiPropReport, type UiRole, type UiSemanticState, type UiSemanticsMap, type UiSemanticsPatch, type UiSemanticsRecord, type UiSemanticsReport, type UiStreamReport, type UiTreeNode, type UiTreeSnapshot, type UndoShortcutOptions, UndoStack, type UndoStackOptions, type UndoTransaction, type UndoableOptions, type ViewOf, type WebMcpChoice, WorkerApp, type WorkerAppOptions, type WorkerHandle, applyPatch, applyPatches, audioClock, bind, bounds, buildPath, channel, channelSchema, classifyStorageError, computed, controlled, createApp, createChannelRegistry, createComponent, createShellHistory, createSyncApp, debounced, defineChannel, derive, describeChannel, describeStream, diffProjection, each, fanOut, findUnplainPath, formatAge, formatNodePath, formatNodeReport, formatStream, formatUrl, input, internalState, into, isChannelClientMessage, isChannelHostMessage, isClassComponent, isComponentElement, isHubMessage, isOutputTarget, isPortErrorMessage, isPortHandshake, markInstant, markNow, measureSpan, mutate, observeColorScheme, observeMediaQuery, observeReducedMotion, output, parseUrl, performShellStorage, performanceMarksEnabled, persisted, pick, pickKeys, portHandle, printPropValue, provide, registerUndoShortcuts, renderRoot, requirePlainData, resource, route, select, serve, serveChannels, servePorts, setPerformanceMarks, shellStorageDenied, show, storageErrorMessage, storageReadFailure, storageReadValue, structurallyEqual, themeTokenCell, throttled, to, treeText, undoable, viewKeys, workerHandle, writeClipboard };

package/dist/index.js

@@ -1949,6 +1949,35 @@ var ShellService = class {
 		});
 	}
 	/**
+	* Opens this application at one of its own urls, somewhere new: what
+	* a Cmd-click or a Ctrl-click on an in-app link asks for.
+	*
+	* Not `openUrl`, because the two urls are different kinds of thing.
+	* `openUrl` takes an address that already means something to the
+	* browser. This takes the router's url, `/epic/BUD-12?story=BUD-13`,
+	* which means something only to this application, and only the
+	* shell knows what address shows the application at it: a path on
+	* the page's origin, a fragment on the page's own address, a tab in
+	* the product the app is embedded in, or a new native window. The
+	* render thread cannot know which, so it names the route and the
+	* shell decides.
+	*
+	* What each shell does, in order: the host's `onOpenRoute` if it gave
+	* one; otherwise a new tab at the address the history gives for the
+	* url (`ShellHistory.href`); otherwise, where there is no address,
+	* which is `memory` mode, the shell follows the url in place, exactly
+	* as `RouterService.navigate` would, rather than doing nothing.
+	*
+	* The current screen does not navigate. Nothing comes back, as with
+	* `openUrl`. With no shell installed the request is dropped.
+	*/
+	openRoute(url) {
+		this.handler?.({
+			type: "openRoute",
+			url
+		});
+	}
+	/**
 	* Replaces the page with `url`, leaving the application.
 	*
 	* Not the router's `navigate`, which moves between screens *inside*
@@ -3761,6 +3790,80 @@ function createShellHistory(options = {}, host = typeof window === "undefined" ?
 	if (mode === "memory" || host === void 0) return new MemoryHistory(options.initialUrl ?? "/");
 	return new BrowserHistory(host, mode, options.base ?? "");
 }
+/**
+* The history an app runs against, and whether the app may dispose it.
+*
+* Options are turned into a history here, and that history is the
+* app's to dispose with everything else it made. A history passed in
+* ready-made is used as it is and left alone at the end, by the rule
+* `appLogicWorker` already follows: what the app made, it disposes;
+* what it was handed, it leaves to whoever handed it. That is also
+* what keeps a host's history alive across a remount, which disposes
+* the app and builds it again around the same object.
+*/
+function resolveShellHistory(source) {
+	if (isShellHistory(source)) return {
+		history: source,
+		owned: false
+	};
+	return {
+		history: createShellHistory(source),
+		owned: true
+	};
+}
+/**
+* Tells a ready-made history from options by its methods.
+*
+* Options are plain data and never carry a function, so the presence of
+* `push` and `onChange` as functions is unambiguous. It is checked by
+* behaviour rather than by `instanceof` because the histories worth
+* passing are adapters an embedder wrote, not classes from here.
+*/
+function isShellHistory(value) {
+	return value !== void 0 && typeof value.push === "function" && typeof value.onChange === "function";
+}
+/**
+* Opens the app at `url` somewhere new, as the shell's answer to
+* `ShellService.openRoute`.
+*
+* In this order, and the order is the decision. A host's own handler
+* wins, because an app embedded in another product or in a desktop
+* window knows what a new tab means there and a browser default would
+* be wrong in both. Without one, the history is asked for the address
+* that holds `url`, and that address is opened. Without an address,
+* which is `memory` mode and any handed-in history with no `href`, the
+* link is followed in place: a Cmd-click that did nothing at all would
+* read as a broken link, and arriving at the destination in the window
+* already open is what a browser does with a modifier it cannot honour.
+*
+* Shared by `WorkerApp` and `GessoApp`, which differ only in how a url
+* reaches the router, so it is passed in.
+*/
+function openRouteWith(handler, url, history, open, followInPlace) {
+	if (handler !== void 0) {
+		handler(url);
+		return;
+	}
+	const address = history?.href?.(url) ?? null;
+	if (address !== null) {
+		open(address);
+		return;
+	}
+	followInPlace(url);
+}
+/**
+* Stops an app hearing about a history it is done with.
+*
+* A history the app made is disposed, which drops its listeners and
+* its window events with it. One it was handed is not the app's to
+* dispose, so the listener is replaced with one that does nothing:
+* the host's history goes on working, and a back button pressed after
+* the app is gone no longer reaches it.
+*/
+function releaseShellHistory(history, owned) {
+	if (owned) history.dispose();
+	else history.onChange(() => {});
+}
 var MemoryHistory = class {
 	entries;
 	index = 0;
@@ -3791,6 +3894,10 @@ var MemoryHistory = class {
 	dispose() {
 		this.listener = null;
 	}
+	/** No address: a url kept here names no page another tab could load. */
+	href() {
+		return null;
+	}
 	step(delta) {
 		const next = this.index + delta;
 		if (next < 0 || next >= this.entries.length) return;
@@ -3858,6 +3965,17 @@ var BrowserHistory = class {
 		this.host.removeEventListener("popstate", this.onPopState);
 		this.host.removeEventListener("hashchange", this.onHashChange);
 	}
+	/**
+	* The address `push` would write for `url`, for a new tab to open.
+	*
+	* Relative, as `pushState` takes it, and resolved against the page by
+	* whatever opens it: `/epic/2` in `path` mode, and the page's own
+	* path and query with the fragment set in `hash` mode, so the new tab
+	* loads the same document and starts on the same screen.
+	*/
+	href(url) {
+		return this.toHref(url);
+	}
 	report() {
 		const url = this.url;
 		if (url === this.written) return;
@@ -4078,6 +4196,8 @@ var WorkerApp = class {
 		right: false
 	};
 	history = null;
+	/** True only when the history was made here from options; see `resolveShellHistory`. */
+	ownsHistory = false;
 	/** True once the render worker has answered `ready` at least once. */
 	ready = false;
 	/** The running `requestAnimationFrame` handle, when ticks are wanted. */
@@ -4439,8 +4559,9 @@ var WorkerApp = class {
 		this.proxy = null;
 		this.mirror?.dispose();
 		this.mirror = null;
-		this.history?.dispose();
+		if (this.history !== null) releaseShellHistory(this.history, this.ownsHistory);
 		this.history = null;
+		this.ownsHistory = false;
 		this.detachInput?.();
 		this.detachInput = null;
 		this.audio?.dispose();
@@ -4548,6 +4669,16 @@ var WorkerApp = class {
 			openUrlWith(this.options.onOpenUrl, message.url);
 			return;
 		}
+		if (message.type === "openRoute") {
+			openRouteWith(this.options.onOpenRoute, message.url, this.history, (address) => window.open(address, "_blank", "noopener"), (url) => {
+				this.history?.push(url);
+				this.post({
+					type: "url",
+					url
+				});
+			});
+			return;
+		}
 		if (message.type === "redirect") {
 			redirectWith(this.options.onRedirect, message.url, window.location);
 			return;
@@ -4595,8 +4726,9 @@ var WorkerApp = class {
 	* the screen that url names, not on its root.
 	*/
 	attachHistory() {
-		const history = createShellHistory(this.options.history);
+		const { history, owned } = resolveShellHistory(this.options.history);
 		this.history = history;
+		this.ownsHistory = owned;
 		history.onChange((url) => this.post({
 			type: "url",
 			url
@@ -9701,6 +9833,7 @@ var GessoApp = class {
 	accessibilityEnabled;
 	adapter;
 	historyOptions;
+	onOpenRoute;
 	running = false;
 	resizeObserver = null;
 	proxy = null;
@@ -9708,6 +9841,8 @@ var GessoApp = class {
 	audio = null;
 	mirror = null;
 	history = null;
+	/** True only when the history was made here from options; see `resolveShellHistory`. */
+	ownsHistory = false;
 	detachVisibility = null;
 	detachFileDrop = null;
 	/** Pickers and remembered handles, made on the first file request. */
@@ -9728,6 +9863,7 @@ var GessoApp = class {
 		this.inputEnabled = options.input ?? true;
 		this.accessibilityEnabled = options.accessibility ?? true;
 		this.historyOptions = options.history;
+		this.onOpenRoute = options.onOpenRoute;
 		this.colorSchemePreference = options.colorScheme ?? "auto";
 		this.runtime = new GessoRuntime({
 			root: options.root,
@@ -9931,8 +10067,9 @@ var GessoApp = class {
 		this.detachColorScheme = null;
 		this.detachViewportInsets?.();
 		this.detachViewportInsets = null;
-		this.history?.dispose();
+		if (this.history !== null) releaseShellHistory(this.history, this.ownsHistory);
 		this.history = null;
+		this.ownsHistory = false;
 		this.adapter.detach();
 		this.resizeObserver?.disconnect();
 		this.resizeObserver = null;
@@ -10014,8 +10151,9 @@ var GessoApp = class {
 	* be a difference between the two hosts that nothing declared.
 	*/
 	attachHistory() {
-		const history = createShellHistory(this.historyOptions);
+		const { history, owned } = resolveShellHistory(this.historyOptions);
 		this.history = history;
+		this.ownsHistory = owned;
 		this.runtime.onShellRequest((request) => this.handleShellRequest(request, history));
 		history.onChange((url) => this.runtime.setUrl(url));
 		this.runtime.setUrl(history.url);
@@ -10041,6 +10179,14 @@ var GessoApp = class {
 			else history.forward();
 			return;
 		}
+		if (request.type === "openRoute") {
+			const view = isCanvasElement(this.canvas) ? this.canvas.ownerDocument.defaultView : null;
+			openRouteWith(this.onOpenRoute, request.url, view === null ? null : history, (address) => view?.open(address, "_blank", "noopener"), (url) => {
+				history.push(url);
+				this.runtime.setUrl(url);
+			});
+			return;
+		}
 		if (!isCanvasElement(this.canvas)) {
 			if (request.type === "popup") this.runtime.settlePopup(request.id, false);
 			else if (request.type === "storage") this.runtime.settleStorage(request.id, shellStorageDenied());
@@ -10204,6 +10350,9 @@ var GessoAppBuilder = class {
 	/**
 	* How the app's url is kept: `path` (pushState, the default in a
 	* browser), `hash`, or `memory`. See `shellHistory`.
+	*
+	* Or a `ShellHistory` made elsewhere, for an app embedded in a page
+	* whose address belongs to its host; see `GessoAppOptions.history`.
 	*/
 	useHistory(history) {
 		this.historyOptions = history;
@@ -11393,6 +11542,10 @@ var RenderWorkerApp = class {
 				type: "openUrl",
 				url: request.url
 			});
+			else if (request.type === "openRoute") this.host.postMessage({
+				type: "openRoute",
+				url: request.url
+			});
 			else if (request.type === "redirect") this.host.postMessage({
 				type: "redirect",
 				url: request.url