@a2f0/skyline 0.1.6 → 0.2.1

package/README.md

@@ -22,7 +22,7 @@ WebGL and the 3D pages need it.
 
 | Page | Shows | Docs |
 | --- | --- | --- |
-| `index.html` | The viewer: opens on the 3D skyline, with the enhanced drawing, the original drawing, and a WebGL prototype one button away | [The viewer](docs/viewer.md) |
+| `index.html` | The viewer, mounted as the package mounts it: opens on the 3D skyline, with the enhanced drawing, the original drawing, and a WebGL prototype one button away | [The viewer](docs/viewer.md) |
 | `skyline-3d.html` | The full-screen 3D skyline on its own: camera views, streets, footprints, celebratory lights, and a building menu | [Full-screen 3D skyline](docs/viewer.md#full-screen-3d-skyline) |
 | `building-detail.html?building=<id>` | One mapped building alone on its platform | [Building menu and detail](docs/viewer.md#building-menu-and-detail) |
 | `skyline-study.html` | The 3D scene over the drawing, in the geographic layout or the original drawing's fit | [3D studies](docs/studies.md#skyline-study) |
@@ -32,8 +32,8 @@ WebGL and the 3D pages need it.
 ## Package
 
 The repository also builds [`@a2f0/skyline`](https://www.npmjs.com/package/@a2f0/skyline), an ESM
-package with the complete embeddable viewer, reusable Three.js scenes and building models, and
-TypeScript declarations. Every merge to `main` publishes a new version to npm; run
+package that mounts the complete viewer into a host page's own document, in a shadow root, with
+reusable Three.js scenes and building models, and TypeScript declarations. Every merge to `main` publishes a new version to npm; run
 `bun run build:package` or `bun pm pack` to build it locally. [The package guide](docs/package.md)
 covers installing, asset copying, mounting, imports, and releases.
 

package/docs/package.md

@@ -20,7 +20,8 @@ provenance linking it to the commit and workflow run that built it.
 
 From this repository:
 
-Use the pinned Bun version, Node.js 22+ (with npm), and Google Chrome for checks.
+Use the Bun and Node.js LTS versions pinned in `mise.toml`, npm (included with Node),
+and Google Chrome for checks.
 
 ```sh
 bun install --ignore-scripts
@@ -81,15 +82,16 @@ await copySkylineAssets('./public/skyline');
 
 Serve that directory over HTTP at `/skyline/`, preserving all its relative paths.
 The helper copies files into the supplied directory; it does not clear unrelated
-files already there. Use a dedicated directory for these assets. All HTML, CSS,
-SVGs, compiled browser modules, and the viewer's vendored Three.js travel together.
+files already there. Use a dedicated directory for these assets, and clear it before
+copying an upgrade, so files a new version dropped do not linger. All the viewer's
+code, CSS, markup, SVGs and models, and its vendored Three.js, travel together. Copy
+them again whenever you upgrade the package, so the loader you bundle and the viewer
+you serve match.
 
-In `~/github/devopsrockstars`, the existing `packages/frontend/tooling/build.ts`
-copies `packages/frontend/static` into its build. Its development server also
-serves `/static/` directly. A later integration can call the helper with
-`path.join(frontendRoot, 'static', 'skyline')` in both build and development startup,
-then use `/static/skyline/` as the browser URL. Keep the generated directory out of
-that application's Git history.
+In `~/github/devopsrockstars`, `packages/frontend/tooling/build.ts` calls the helper
+when the `skyline3d` flag is on and serves the copy at `/static/skyline/`, the browser
+URL the viewer mounts with. Keep the generated directory out of that application's
+Git history.
 
 ## Mount the complete viewer
 
@@ -100,17 +102,41 @@ const skyline = mountSkyline(container, {
   assetsUrl: '/skyline/',
   title: 'Interactive Chicago skyline',
 });
+await skyline.ready; // optional: the 3D skyline has drawn its first frame
 
 // When the page or component leaves:
 skyline.destroy();
 ```
 
-The container determines the viewer's size and placement; give it an explicit
-height. The viewer fills it through an iframe, which isolates its styles and
-controls from the application's header and CSS. Embedding hides the standalone
-toolbar and study links so they do not overlap the host's navigation. Set
-`navigation: true` to show them. It retains stars, the traced
-loading silhouette, star controls, original comparison, and building details.
+The viewer renders into the host's own document, inside a shadow root that keeps its
+styles and the host's apart. `mountSkyline` returns at once with an instance:
+
+- `element` is the `HTMLElement` it appended to `container`: a region named by the
+  `title` option (default "Interactive Chicago skyline"), with the viewer in its open
+  shadow root. It fills the container, which sets the viewer's size and placement:
+  give the container an explicit height. The element is `aria-busy` until `ready`
+  settles.
+- `ready` resolves once the 3D skyline has drawn its first frame: use it where an
+  iframe's `load` event was used. It rejects when the viewer can't start: when its
+  assets fail to load, the element says why in the viewer's place; when the 3D scene
+  can't start, as without WebGL 2, the scene says why and the original drawing stays
+  one press away. The error is also logged, so a host that ignores `ready` sees no
+  unhandled rejection. A destroyed instance's `ready` never settles.
+- `destroy()` removes the element and releases everything the viewer holds: its WebGL
+  renderers and contexts (disposed, then lost on purpose, so remounts never exhaust
+  the browser's contexts), animation frames, resize observers, media-query, pointer
+  and keyboard listeners, the building detail, and loads still in flight. Calling it
+  again does nothing, and destroying while the viewer still loads is safe. Unlike a
+  frame, the viewer doesn't stop when its element merely leaves the page: always call
+  `destroy`.
+
+The viewer shows what the embedded viewer always has: the twinkling stars and the
+traced loading silhouette, the 3D skyline with its control bar, the OpenStreetMap
+credit, a small **show original** button until the first 3D frame (and again if the
+graphics context is lost), so the original drawing stays reachable even if WebGL or
+the scene's code cannot load, building details in a panel over the skyline, and
+reduced motion. `F`, pressed inside the viewer, shows its element fullscreen.
+
 The scene's control bar starts folded behind its star; set `controls: 'open'` to
 start it open, with no fold, from its first frame. Visitors can still fold it.
 Open, the bar shows the camera hint and the OpenStreetMap credit for the streets
@@ -118,14 +144,34 @@ and footprints. Set `attribution: false` to leave the credit out. OpenStreetMap'
 [licence](https://www.openstreetmap.org/copyright) requires crediting its contributors
 wherever its data is shown, so do this only when the host page credits
 © OpenStreetMap contributors itself.
-A small independent **show original** button remains available until the first
-3D frame succeeds, and reappears if the graphics context is lost. The SVG stays
-reachable even if WebGL, the scene document, or its bootstrap script cannot load.
-Unmounting removes the entire document, its event handlers, and its WebGL context.
+
 Imports themselves do not access `window` or `document`, so server rendering and
 lazy loading are safe. Asset URLs may be relative or absolute HTTP(S) directories.
 
-For the existing React route in `devopsrockstars`, an effect owns this lifecycle:
+### Living in the host's page
+
+- The host's styles stay out: the element sets `all: initial` and `direction: ltr` on
+  itself, so nothing the host's rules set is inherited into the viewer, and the
+  viewer sets its own type, colours and custom properties. Its styles stay in its
+  shadow root. It lays itself out by its own size, through container queries, not the
+  window's: a small window in a desktop gets the narrow layout.
+- Presses and keys bubble out to the host, as any other content's do: a press inside
+  the viewer reaches the host's `pointerdown` and `mousedown` listeners, so a host's
+  window can raise itself and its menus close. Its keys act only where they are
+  pressed: `F`, `Escape` and its arrow, zoom and menu keys work while focus is inside
+  that viewer, and arrive with `defaultPrevented` set, so two viewers, or a viewer and
+  the host, never take each other's keys.
+- The viewer never scrolls the host page: it moves focus with `preventScroll`, and
+  its building detail is a non-modal panel (`role="dialog"`, not `aria-modal`), so the
+  rest of the page stays usable.
+- It works wherever the host puts it: in the host's own shadow root, open or closed, and
+  under a host's CSS transform, where its menus and tooltip still open at the pointer.
+- Each instance is independent: two viewers can run side by side on one page.
+
+### React
+
+An effect owns the lifecycle. Mounting is synchronous, so React Strict Mode's mount,
+destroy and mount again in development works:
 
 ```tsx
 import React, { useEffect, useRef } from 'react';
@@ -136,6 +182,8 @@ export default function Skyline() {
   useEffect(() => {
     const skyline = mountSkyline(container.current!, {
       assetsUrl: '/static/skyline/',
+      // The page already runs Three.js: share it (see below).
+      three: import('@a2f0/skyline/three'),
     });
     return () => skyline.destroy();
   }, []);
@@ -144,15 +192,95 @@ export default function Skyline() {
 }
 ```
 
-Keep the host's header, footer, sizing, and stacking in that application. Importing
-`@a2f0/skyline` loads only the small mounting helper; scene geometry loads inside
-the viewer when it boots. The cleanup also supports React Strict Mode's remounts.
+Keep the host's header, footer, sizing, and stacking in that application.
+
+### Share the page's Three.js
+
+The viewer's 3D scene renders with Three.js r186. By default it loads the copy in the
+assets, `vendor/three-r186.bundle.js` (about 140 KB compressed), only when a scene
+first needs it, so a host needs no `three` dependency. A page that already runs
+Three.js would then run two engines, and Three.js warns "Multiple instances of
+Three.js being imported". Such a page can share its own instead, through the `three`
+option:
+
+```ts
+mountSkyline(container, { assetsUrl: '/static/skyline/', three: import('@a2f0/skyline/three') });
+```
+
+`@a2f0/skyline/three` re-exports from the host's `three` (the optional peer,
+`~0.186.0`) exactly the classes the viewer uses, and `OrbitControls`, so a bundler keeps
+no more of the engine than the viewer needs; the viewer then never requests its own
+copy. Pass the module, or a promise of it as above, which keeps it out of the host's
+first bundle when the viewer mounts later. The page's first scene takes the engine
+when its code first loads, and later instances on the page share it; if the promise
+rejects, the viewer warns and loads its own copy. A host without `three` simply leaves
+the option out.
+
+### How the viewer's code loads
+
+The package's module (`lib/`) is a small loader that a host bundles (under 4 KB). When
+it mounts, it imports the viewer's code from the assets (`skyline-viewer.js`) with a
+dynamic `import()` that carries `webpackIgnore`, `turbopackIgnore` and `@vite-ignore`
+comments, so webpack (including Next.js with `--webpack`), Turbopack and Vite leave it
+to the browser; Rollup, esbuild and Bun leave an import of a variable alone anyway. A
+bundler that tried to resolve it would fail to build: tell it to ignore that import.
+The viewer then loads its stylesheets, the scene's markup from `skyline-3d.html`, its
+stars from `stars.svg`, and the scene's modules and models from the same directory.
+Each module loads once per page, however many viewers mount.
+
+### Content security policy and other origins
+
+The viewer runs in the host's page, under the host's content security policy. A host
+with one must allow the assets' origin (usually `'self'`) in `script-src`,
+`style-src` and `connect-src` (the viewer fetches its markup and stars), and inline
+styles in `style-src`, which the viewer sets on its elements. Serve the assets from
+the host's origin when you can; on another origin, every file must allow the page's
+origin through CORS. The viewer's code runs with the host page's privileges wherever
+it is served from: serve it only from an origin you trust.
+
+### For tests
+
+`element.shadowRoot` holds the viewer: its 3D canvas is `#building` and the scene's
+loading indicator `#loading`, hidden at the first frame. The region drops `aria-busy`
+when `ready` settles. WebDriver and Playwright reach into open shadow roots; code run
+in the page reads `element.shadowRoot.querySelector(...)`.
+
+### From 0.1 (iframe) to 0.2
+
+Before 0.2, the viewer ran in an iframe. Hosts upgrading:
+
+- `element` is the viewer's region element, not an `HTMLIFrameElement`: wait for
+  `ready` instead of the frame's `load` event, and reach the viewer through
+  `element.shadowRoot` instead of `contentDocument`. There are no nested frames: the
+  3D scene and its building detail render in the same shadow root (the detail in a
+  shadow root of its own, inside the scene's panel), and they no longer post
+  `skyline:` messages to each other.
+- `navigation` is gone. It showed the site's own toolbar, which only the site's
+  `index.html` shows now. The viewer's options are `assetsUrl`, `title`, `controls`,
+  `attribution` and `three`.
+- Presses inside the viewer reach the host as any other press does, so a workaround
+  that raised a window when a frame took focus is no longer needed.
+- The viewer no longer has its own window: `window.__buildingStudy`, which tests read
+  inside the scene's frame, is not set on the host's window.
+- Copy the assets again: the viewer's code is new files (`skyline-viewer.js`,
+  `viewer.css` and others).
+
+### Limitations
+
+- Removing the element without calling `destroy()` leaves the viewer running.
+- If the viewer's or scene's code fails to load, as on a dropped connection, the
+  browser keeps that failure for the page: later mounts on the same page fail the same
+  way until it reloads. A frame used to retry with a new document.
+- The site's own `index.html` shows two prototypes from its toolbar, the hover-scripted
+  enhanced drawing and the WebGL prototype, as pages of their own in frames; a host's
+  viewer never shows them.
 
 ## Import a scene or a building
 
 For an application that owns its own renderer, install `three` from the r186
 series (`~0.186.0`). `devopsrockstars` already uses a compatible version. The
-complete iframe viewer does not need this peer; scene/model imports do.
+mounted viewer needs this peer only to share the host's engine; scene/model imports
+always do.
 
 ```ts
 import { Group } from 'three';
@@ -205,7 +333,14 @@ overlap, and when merges land together only the newest pending run starts, so in
 versions can be skipped on npm.
 
 The workflow first runs the full `bun run check`, browser suites included, in the runner's
-Google Chrome. Only when that passes does it build and pack the tarball; both jobs run without
+Google Chrome with the pinned Node.js LTS. The dependency audit is part of that
+check: it needs the registry network, and any advisory in the locked dependency
+graph fails the check and blocks publishing until addressed.
+If that changes after merge, report the failed release, fix the dependency or
+registry failure, then re-dispatch the workflow to release the merged version.
+It also runs the
+tarball and viewer package suite on Node.js 22 to verify the supported minimum.
+Only when those pass does it build and pack the tarball; both jobs run without
 publish rights, and the publish job receives only that tarball and runs
 `npm publish --ignore-scripts`. Dispatching the workflow on another branch
 (`gh workflow run npm-publish.yml --ref <branch>`) runs only the tests, in a queue of its own,
@@ -224,6 +359,9 @@ Then, in the package's settings on npmjs.com, add a GitHub Actions trusted publi
 repository `a2f0/skyline`, workflow `npm-publish.yml`, and environment `npm`, and re-run
 the workflow; it reports the version as already published.
 
+The Sharp override in the tarball is repository development tooling policy; npm
+and Bun consumers use their own root overrides, so it does not pin their dependencies.
+
 The package is ESM only, with no CommonJS entrypoint. Building requires this repository's
 Bun/TypeScript tools; consuming the published package requires neither Bun nor build
 scripts. Metadata uses `UNLICENSED` and preserves the third-party notices in

package/lib/skyline-package.d.ts

@@ -1,31 +1,39 @@
+import { type SkylineInstance } from "./skyline-shell.js";
+import type { SkylineThree } from "./three-engine.js";
 export type { BuildingModel, Vec2, Vec3 } from "./models/building-kit.js";
 export type { FitBox, PlatformOptions, ShadowCameraOptions, StudyView, StudyLayout, StudyLabel } from "./study-types.js";
 export type { GeographicSkyline } from "./skyline-scene.js";
+export type { SkylineInstance } from "./skyline-shell.js";
+export type { SkylineThree } from "./three-engine.js";
 export interface SkylineOptions {
-    /** Directory serving the package's viewer assets, e.g. "/static/skyline/". */
-    assetsUrl: string | URL;
-    /** Accessible title for the embedded viewer. */
-    title?: string;
-    /** Show the standalone toolbar and study links. Hidden by default when embedded. */
-    navigation?: boolean;
+    /**
+     * The directory serving the package's viewer assets, as copied by `copySkylineAssets`
+     * from `@a2f0/skyline/build`; for example "/static/skyline/". Relative URLs resolve
+     * against the page. The viewer's code, styles, drawings and models load from it.
+     */
+    readonly assetsUrl: string | URL;
+    /** The viewer's accessible name: `element` is a region with this label. */
+    readonly title?: string;
     /** Start the 3D scene's control bar open, or folded behind its star. Closed by default. */
-    controls?: "open" | "closed";
+    readonly controls?: "open" | "closed";
     /**
      * Show the OpenStreetMap credit with the 3D scene's controls. Shown by default. OpenStreetMap's
      * licence requires that credit wherever its data appears, so hide it only when the host page
      * credits OpenStreetMap contributors itself.
      */
-    attribution?: boolean;
-}
-export interface SkylineInstance {
-    /** The viewer's frame; its styles are isolated from the host application. */
-    readonly element: HTMLIFrameElement;
-    /** Removes the viewer, releasing its document, event handlers and WebGL context. */
-    destroy(): void;
+    readonly attribution?: boolean;
+    /**
+     * The host's own Three.js, for a page that already runs it: pass `@a2f0/skyline/three`, or a
+     * dynamic import of it, and the scene renders with the host's engine instead of downloading
+     * the copy in the assets. The page's first scene takes the engine; leave it out to use the
+     * assets' copy, which needs no `three` dependency.
+     */
+    readonly three?: SkylineThree | PromiseLike<SkylineThree>;
 }
 /**
- * Mounts the complete interactive viewer inside a host-owned container. Importing
- * this module never touches the DOM; call it after mounting a browser component.
- * The container controls placement and size. Destroy it when that component leaves.
+ * Mounts the complete interactive viewer filling `container`, inside a shadow root. It
+ * returns at once; `ready` settles when the 3D skyline shows. The container sets the viewer's
+ * size and placement: give it an explicit height. Call `destroy` when the hosting component
+ * leaves.
  */
-export declare function mountSkyline(container: HTMLElement, { assetsUrl, title, navigation, controls, attribution }: SkylineOptions): SkylineInstance;
+export declare function mountSkyline(container: HTMLElement, { assetsUrl, title, controls, attribution, three }: SkylineOptions): SkylineInstance;

package/lib/skyline-package.js

@@ -1,31 +1,15 @@
+// The browser entrypoint of the @a2f0/skyline package: mounts the viewer in a host-owned
+// container, inside a shadow root in the host's own document. Importing it never touches the
+// DOM, so server rendering and lazy loading are safe. docs/package.md describes the package.
+import { mountViewer } from "./skyline-shell.js";
 /**
- * Mounts the complete interactive viewer inside a host-owned container. Importing
- * this module never touches the DOM; call it after mounting a browser component.
- * The container controls placement and size. Destroy it when that component leaves.
+ * Mounts the complete interactive viewer filling `container`, inside a shadow root. It
+ * returns at once; `ready` settles when the 3D skyline shows. The container sets the viewer's
+ * size and placement: give it an explicit height. Call `destroy` when the hosting component
+ * leaves.
  */
-export function mountSkyline(container, { assetsUrl, title = "Interactive Chicago skyline", navigation = false, controls = "closed", attribution = true }) {
+export function mountSkyline(container, { assetsUrl, title = "Interactive Chicago skyline", controls = "closed", attribution = true, three }) {
     if (controls !== "open" && controls !== "closed")
         throw new TypeError('Skyline controls must be "open" or "closed".');
-    const document = container.ownerDocument;
-    const base = new URL(assetsUrl, document.baseURI);
-    if (!/^(https?:)$/.test(base.protocol))
-        throw new TypeError("Skyline assets must be served over HTTP or HTTPS.");
-    if (base.search || base.hash)
-        throw new TypeError("Skyline assetsUrl must be a directory URL without a query or fragment.");
-    if (!base.pathname.endsWith("/"))
-        base.pathname += "/";
-    const element = document.createElement("iframe");
-    element.title = title;
-    const viewerUrl = new URL("index.html", base);
-    if (!navigation)
-        viewerUrl.searchParams.set("embed", "1");
-    if (controls === "open")
-        viewerUrl.searchParams.set("controls", "open");
-    if (!attribution)
-        viewerUrl.searchParams.set("attribution", "hidden");
-    element.src = viewerUrl.href;
-    element.allowFullscreen = true;
-    element.style.cssText = "display:block;width:100%;height:100%;border:0";
-    container.append(element);
-    return { element, destroy() { element.remove(); } };
+    return mountViewer(container, { assetsUrl, title, controls, attribution, navigation: false, page: false, three });
 }

package/lib/skyline-shell.d.ts

@@ -0,0 +1,69 @@
+import type { SkylineThree } from "./three-engine.js";
+/** What the viewer module is told when it mounts. */
+export interface ViewerContext {
+    /** The slash-terminated directory the assets are served from. */
+    readonly assets: URL;
+    /**
+     * Aborts when the instance is destroyed, or the viewer fails to start. The viewer then
+     * releases everything it holds: its WebGL contexts, animation frames, observers, listeners
+     * outside its root and pending loads. The shell removes the DOM.
+     */
+    readonly signal: AbortSignal;
+    /** Start the 3D scene's control bar open, rather than folded behind its star. */
+    readonly controls: "open" | "closed";
+    /** Show the OpenStreetMap credit with the scene's controls. */
+    readonly attribution: boolean;
+    /**
+     * The site's own toolbar, along the viewer's top: fullscreen, the drawings, the WebGL
+     * prototype, the studies and the stars' debug motion. Only the site's index.html shows it.
+     */
+    readonly navigation: boolean;
+    /** The viewer is its page's whole content, so the page's keys are its keys. */
+    readonly page: boolean;
+    /** The host's Three.js, for the scene to share (three-engine.ts). */
+    readonly three?: SkylineThree | PromiseLike<SkylineThree> | undefined;
+}
+/** What the viewer module exports. */
+export interface ViewerModule {
+    /**
+     * Renders the viewer into `root`, whose stylesheets have loaded, and settles once the 3D
+     * skyline has drawn its first frame: a rejection is a scene that can't start, and the
+     * viewer then says why in place and keeps the drawing one press away.
+     */
+    mount(root: ShadowRoot, context: ViewerContext): Promise<void>;
+}
+/** A mounted viewer. */
+export interface SkylineInstance {
+    /**
+     * The element holding the viewer, appended to the container. The viewer renders into its
+     * open shadow root, which keeps the viewer's styles and the host's apart. It is a region
+     * named by the `title` option, filling the container, and is `aria-busy` until `ready`
+     * settles.
+     */
+    readonly element: HTMLElement;
+    /**
+     * Resolves once the 3D skyline has drawn its first frame; replaces an iframe's `load`
+     * event. Rejects when it can't start, as when its assets fail to load or WebGL is
+     * unavailable: the viewer then says why, in place, and still offers the original drawing
+     * if its own code loaded. Stays pending if the instance is destroyed first.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Removes the viewer and releases its WebGL contexts, animation frames, observers,
+     * listeners, timers and pending loads. Calling it again does nothing.
+     */
+    destroy(): void;
+}
+export interface ViewerOptions extends Omit<ViewerContext, "assets" | "signal"> {
+    /** The assets' directory; relative URLs resolve against the container's document. */
+    readonly assetsUrl: string | URL;
+    /** The viewer's accessible name: `element` is a region with this label. */
+    readonly title: string;
+}
+/** The validated, slash-terminated directory the assets are served from. */
+export declare function assetsBase(document: Document, assetsUrl: string | URL): URL;
+/**
+ * Mounts the viewer in a new element appended to `container`, and returns at once: the
+ * element is in place, and `ready` settles once the 3D skyline shows or can't start.
+ */
+export declare function mountViewer(container: HTMLElement, { assetsUrl, title, ...options }: ViewerOptions): SkylineInstance;

package/lib/skyline-shell.js

@@ -0,0 +1,115 @@
+// The viewer's code and styles, relative to the assets.
+const VIEWER = "skyline-viewer.js";
+const STYLESHEETS = ["study.css", "viewer.css"];
+/** The validated, slash-terminated directory the assets are served from. */
+export function assetsBase(document, assetsUrl) {
+    const base = new URL(assetsUrl, document.baseURI);
+    if (base.protocol !== "http:" && base.protocol !== "https:")
+        throw new TypeError("Skyline assets must be served over HTTP or HTTPS.");
+    if (base.search || base.hash)
+        throw new TypeError("Skyline assetsUrl must be a directory URL without a query or fragment.");
+    if (!base.pathname.endsWith("/"))
+        base.pathname += "/";
+    return base;
+}
+/**
+ * Imports the viewer module from the assets. Hosts bundle this file, but the module is
+ * served with the assets, so the comments ask webpack, Turbopack and Vite to leave the
+ * import to the browser; Rollup, esbuild and Bun leave an import of a variable alone.
+ */
+function importViewer(url) {
+    return import(/* webpackIgnore: true */ /* @vite-ignore */ /* turbopackIgnore: true */ url);
+}
+/** Resolves once `link` has loaded its stylesheet. */
+function loaded(link) {
+    return new Promise((resolve, reject) => {
+        link.addEventListener("load", () => resolve(), { once: true });
+        link.addEventListener("error", () => reject(new Error(`Couldn't load ${link.href}.`)), { once: true });
+    });
+}
+// Set on the element itself, where it outranks the host page's rules: `all: initial` keeps
+// the host's rules for its elements (a `div` or `*` rule) off it, so nothing they set is
+// inherited into the viewer, `direction` (which `all` leaves) keeps a right-to-left page from
+// mirroring the viewer's layout, and the rest sizes it to fill the container.
+const HOST_STYLE = "all:initial;direction:ltr;display:block;position:relative;isolation:isolate;width:100%;height:100%;overflow:hidden";
+// The failure message's own look, since the viewer's stylesheets may be what failed.
+const FAILURE_STYLE = "box-sizing:border-box;height:100%;margin:0;padding:24px;background:#000;color:#aaa;font:12px/1.5 ui-monospace,monospace";
+/** Shows why the viewer couldn't start, in place of the viewer. */
+function showFailure(root, error) {
+    const message = root.ownerDocument.createElement("p");
+    message.style.cssText = FAILURE_STYLE;
+    message.setAttribute("role", "alert");
+    message.textContent = `The Chicago skyline couldn't start: ${error instanceof Error ? error.message : String(error)}`;
+    root.replaceChildren(...[...root.querySelectorAll("link")].filter((link) => link.sheet), message);
+}
+/**
+ * Mounts the viewer in a new element appended to `container`, and returns at once: the
+ * element is in place, and `ready` settles once the 3D skyline shows or can't start.
+ */
+export function mountViewer(container, { assetsUrl, title, ...options }) {
+    const document = container.ownerDocument;
+    const assets = assetsBase(document, assetsUrl);
+    const element = document.createElement("div");
+    element.style.cssText = HOST_STYLE;
+    element.setAttribute("role", "region");
+    element.setAttribute("aria-label", title);
+    element.setAttribute("aria-busy", "true");
+    const root = element.attachShadow({ mode: "open" });
+    const stylesheets = STYLESHEETS.map((name) => {
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = new URL(name, assets).href;
+        return link;
+    });
+    root.append(...stylesheets);
+    container.append(element);
+    // A host's engine that fails to load is the viewer's to report, once its scene asks for it
+    // (three-engine.ts); until then, or if the instance never gets that far, its rejection is
+    // handled here rather than left unhandled.
+    if (options.three)
+        Promise.resolve(options.three).catch(() => { });
+    const controller = new AbortController();
+    let destroyed = false, mounted = false;
+    const context = { ...options, assets, signal: controller.signal };
+    const ready = new Promise((resolve, reject) => {
+        Promise.all([importViewer(new URL(VIEWER, assets).href), ...stylesheets.map(loaded)])
+            .then(async ([viewer]) => {
+            if (destroyed)
+                return;
+            mounted = true;
+            await viewer.mount(root, context);
+        })
+            .then(() => {
+            if (destroyed)
+                return;
+            element.removeAttribute("aria-busy");
+            resolve();
+        }, (error) => {
+            if (destroyed)
+                return;
+            element.removeAttribute("aria-busy");
+            // A viewer that mounted says why its scene can't start, and keeps its drawing;
+            // one that never loaded is replaced by the reason.
+            if (!mounted) {
+                controller.abort(error);
+                showFailure(root, error);
+            }
+            console.error("The Chicago skyline couldn't start:", error);
+            reject(error);
+        });
+    });
+    // The element and the console report a failure, so a host that ignores `ready` sees no
+    // unhandled rejection.
+    ready.catch(() => { });
+    return {
+        element,
+        ready,
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            controller.abort(new DOMException("The Chicago skyline was destroyed.", "AbortError"));
+            element.remove();
+        },
+    };
+}

package/lib/skyline-three.d.ts

@@ -0,0 +1,2 @@
+export { AmbientLight, BoxGeometry, BufferGeometry, Color, DataTexture, DirectionalLight, EdgesGeometry, Float32BufferAttribute, Group, LineBasicMaterial, LineSegments, Mesh, MeshBasicMaterial, MeshToonMaterial, NearestFilter, PCFSoftShadowMap, OrthographicCamera, PerspectiveCamera, Raycaster, RedFormat, Scene, Vector2, Vector3, WebGLRenderer, } from "three";
+export { OrbitControls } from "three/addons/controls/OrbitControls.js";

package/lib/skyline-three.js

@@ -0,0 +1,7 @@
+// `@a2f0/skyline/three`: the part of the host's own Three.js the viewer uses, for
+// `mountSkyline`'s `three` option. Importing it needs the `three` peer (~0.186.0). Pass the
+// module, or a dynamic import of it, so the viewer shares the host's engine:
+//
+//   mountSkyline(container, { assetsUrl, three: import("@a2f0/skyline/three") });
+export { AmbientLight, BoxGeometry, BufferGeometry, Color, DataTexture, DirectionalLight, EdgesGeometry, Float32BufferAttribute, Group, LineBasicMaterial, LineSegments, Mesh, MeshBasicMaterial, MeshToonMaterial, NearestFilter, PCFSoftShadowMap, OrthographicCamera, PerspectiveCamera, Raycaster, RedFormat, Scene, Vector2, Vector3, WebGLRenderer, } from "three";
+export { OrbitControls } from "three/addons/controls/OrbitControls.js";

package/lib/three-engine.d.ts

@@ -0,0 +1,16 @@
+import type * as THREE from "three";
+import type { OrbitControls } from "three/addons/controls/OrbitControls.js";
+/**
+ * The part of Three.js the viewer uses: `@a2f0/skyline/three` exports exactly this from the
+ * host's `three`, so a host's bundler keeps no more of its engine than the viewer needs.
+ */
+export type SkylineThree = Pick<typeof THREE, "AmbientLight" | "BoxGeometry" | "BufferGeometry" | "Color" | "DataTexture" | "DirectionalLight" | "EdgesGeometry" | "Float32BufferAttribute" | "Group" | "LineBasicMaterial" | "LineSegments" | "Mesh" | "MeshBasicMaterial" | "MeshToonMaterial" | "NearestFilter" | "PCFSoftShadowMap" | "OrthographicCamera" | "PerspectiveCamera" | "Raycaster" | "RedFormat" | "Scene" | "Vector2" | "Vector3" | "WebGLRenderer"> & {
+    readonly OrbitControls: typeof OrbitControls;
+};
+/**
+ * Offers a host's engine to the scene. The page's first scene takes the engine once, when its
+ * code first loads: an engine offered later, or by a second instance, is not used.
+ */
+export declare function provideThree(three: SkylineThree | PromiseLike<SkylineThree>): void;
+/** The host's engine, if one was offered. */
+export declare function providedThree(): Promise<SkylineThree> | undefined;

package/lib/three-engine.js

@@ -0,0 +1,12 @@
+let provided;
+/**
+ * Offers a host's engine to the scene. The page's first scene takes the engine once, when its
+ * code first loads: an engine offered later, or by a second instance, is not used.
+ */
+export function provideThree(three) {
+    provided ??= Promise.resolve(three);
+}
+/** The host's engine, if one was offered. */
+export function providedThree() {
+    return provided;
+}