@a2f0/skyline 0.0.0-stage → 0.1.1

package/NOTICE.md

@@ -0,0 +1,20 @@
+# Notices
+
+Package metadata uses `UNLICENSED`. This release does not add a license for the
+project's source code or artwork.
+
+The self-contained viewer includes Three.js r186 under the MIT license. Its full
+notice is packaged at `site/vendor/THREE-LICENSE.txt`. Imported scene and building
+modules use the consuming application's `three` dependency instead.
+
+Mapped building footprints, building parts, and streets contain data from
+© OpenStreetMap contributors, under the Open Database License (ODbL) 1.0:
+
+- [OpenStreetMap copyright and attribution](https://www.openstreetmap.org/copyright)
+- [Open Database License](https://opendatacommons.org/licenses/odbl/1-0/)
+
+The complete viewer preserves its OpenStreetMap credit. Applications rendering
+the scene/model modules themselves should carry the same credit. The data retains
+its source way IDs and versions in `models/skyline-geography-data`; extraction
+dates, measurements, assumptions, and source links are documented in the
+repository's `docs/skyline-geography.md`.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# Chicago Skyline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A grayscale Chicago skyline traced from a 2013 photograph taken on the lakefront by the Adler
+Planetarium, and a 3D city of 34 mapped buildings seen through that photograph's own camera.
+Hover a building for its name, right-click it for a close look, or switch to the animated drawing
+it was fitted to. It is live at [skyline.devopsrockstars.com](https://skyline.devopsrockstars.com).
+
+## Run it locally
+
+With [Bun](https://bun.sh) installed (the version is pinned in `mise.toml`):
+
+```sh
+bun install --ignore-scripts
+bun run build:site
+python3 -m http.server -d dist
+```
+
+Then open `http://localhost:8000`. Serve `dist/` over HTTP rather than opening files directly:
+WebGL and the 3D pages need it.
+
+## Pages
+
+| 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) |
+| `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) |
+| `building-study.html` | The Crain Communications Building beside its illustration | [3D studies](docs/studies.md#single-building-study) |
+| `skyline-webgl.html` | The drawing's layers rendered as GPU textures | [WebGL prototype](docs/viewer.md#webgl-prototype) |
+
+## 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
+`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.
+
+## Development
+
+```sh
+sh scripts/git/install-hooks.sh   # once per clone
+bun run check                     # typecheck, unit and browser suites; needs Google Chrome
+bun run deploy                    # publish to Cloudflare; needs Node.js 22+ and wrangler login
+```
+
+[Development](docs/development.md) explains the checks, hooks, and PR workflow, and
+[Deploying](docs/deploying.md) the release and its verification. To add a building or improve one,
+start with [Adding a building](docs/adding-a-building.md) or the
+[fidelity queue](docs/building-fidelity.md). Coding agents follow [`AGENTS.md`](AGENTS.md).
+
+All documentation is indexed in [`docs/`](docs/README.md).

package/docs/package.md

@@ -0,0 +1,222 @@
+# Using Skyline as a package
+
+`@a2f0/skyline` provides the complete viewer and separate Three.js scene/building
+modules. Package builds emit ordinary ESM JavaScript and TypeScript declarations;
+consumers of the published package do not compile repository sources or run installation
+scripts. Browser code and Node/Bun build helpers have separate entrypoints.
+
+## Install from npm
+
+```sh
+bun add --exact @a2f0/skyline
+# or
+npm install --save-exact @a2f0/skyline
+```
+
+Every merge to `main` publishes a new version (see [Releases](#releases)), each with npm
+provenance linking it to the commit and workflow run that built it.
+
+## Build and pack
+
+From this repository:
+
+Use the pinned Bun version, Node.js 22+ (with npm), and Google Chrome for checks.
+
+```sh
+bun install --ignore-scripts
+bun run check:package
+bun pm pack --destination /tmp
+```
+
+`prepack` builds the package automatically. The result is
+`/tmp/a2f0-skyline-<version>.tgz`, named for the version in `package.json`. To try it
+before publishing, install that tarball in the consuming application:
+
+```sh
+bun add /tmp/a2f0-skyline-<version>.tgz
+```
+
+The tarball includes `lib/` (ESM and declarations), `site/` (the complete static
+viewer), package documentation, and third-party notices. Sources, test fixtures,
+credentials, deployment configuration, and the unused source photograph are
+excluded. No viewer assets load from a CDN.
+
+## Install from GitHub with Bun
+
+GitHub dependencies contain repository sources, rather than the generated
+`lib/` and `site/` directories in a published tarball. Pin a full commit SHA:
+
+```sh
+bun add github:a2f0/skyline#<full-commit-sha>
+```
+
+Build the installed source explicitly with your application's pinned Bun and
+TypeScript tools. Add this root `package.json` script so fresh installs and CI
+prepare the same artifacts:
+
+```json
+{
+  "scripts": {
+    "postinstall": "bun node_modules/@a2f0/skyline/scripts/build-package.ts"
+  }
+}
+```
+
+The host needs TypeScript 7, `@tsconfig/strictest`, `@types/bun`, and `@types/node`
+as development dependencies. The build resolves those tools from the host;
+it does not install Skyline's development dependencies or run dependency
+lifecycle scripts. Keep `trustedDependencies` unchanged. Run `bun install` after
+adding the script. Both the published tarball and this GitHub build expose the
+same entrypoints, declarations, and complete viewer assets.
+
+## Copy the viewer assets
+
+Import the build helper from a Node 22+ or Bun build script:
+
+```ts
+import { copySkylineAssets } from '@a2f0/skyline/build';
+
+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.
+
+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.
+
+## Mount the complete viewer
+
+```ts
+import { mountSkyline } from '@a2f0/skyline';
+
+const skyline = mountSkyline(container, {
+  assetsUrl: '/skyline/',
+  title: 'Interactive Chicago skyline',
+});
+
+// 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.
+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:
+
+```tsx
+import React, { useEffect, useRef } from 'react';
+import { mountSkyline } from '@a2f0/skyline';
+
+export default function Skyline() {
+  const container = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const skyline = mountSkyline(container.current!, {
+      assetsUrl: '/static/skyline/',
+    });
+    return () => skyline.destroy();
+  }, []);
+
+  return <div id="skyline" ref={container} style={{ width: '100%', height: '100vh' }} />;
+}
+```
+
+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.
+
+## 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.
+
+```ts
+import { Group } from 'three';
+import { createGeographicSkyline, skylineAzimuth } from '@a2f0/skyline/scene';
+import { createCrainBuilding } from '@a2f0/skyline/models/crain-communications';
+import type { BuildingModel, StudyView } from '@a2f0/skyline';
+
+const skyline = createGeographicSkyline();
+const group = new Group();
+for (const model of skyline.models) group.add(model.building);
+group.add(skyline.ground.group);
+
+const crain: BuildingModel = createCrainBuilding();
+const view: StudyView = skyline.drawingView;
+```
+
+The scene factory returns models, ground, camera/framing settings, drawing view,
+comparison views, and labels. Importing a module does not construct the scene.
+Create it when needed. Individual building modules remain available under
+`@a2f0/skyline/models/<filename>`, without the `.js` extension. Their Three.js
+objects use the consuming application's engine, so they can join its existing
+scene without bundling a second engine. The caller owns rendering, controls,
+resource disposal, and OpenStreetMap attribution in this mode.
+
+The geographic Blue Cross model exposes an optional `illumination`
+controller; no other model has one. Its read-only `presets` list gives the
+supported IDs, labels, wording and adaptation flag. Call `set(id)` to replace
+its message or `set(null)` to turn it off, then render your scene. An
+unsupported ID throws without changing the current display. `active` reports
+the selection and `litWindows` counts illuminated office panes. Each instance
+has its own state. Use the model from `createGeographicSkyline()` or
+`createGeographicBuilding()` for these displays.
+
+`@a2f0/skyline/models/building-kit` exposes the same plan runs and mesh builder
+used by this repository, for adding buildings. Coordinate and model assumptions
+are in [the geography notes](skyline-geography.md). Asset paths are also available
+through `@a2f0/skyline/assets/<path>` for build tooling that resolves package
+files directly; bundlers do not automatically copy that directory.
+
+## Releases
+
+ship-pr bumps the `package.json` patch version on every merge (see
+[the PR workflow](development.md#pr-workflow)), and the
+[publish workflow](../.github/workflows/npm-publish.yml) publishes each version newer than
+npm's `latest` with [trusted publishing](https://docs.npmjs.com/trusted-publishers) and
+provenance. No npm token is stored: the publish job runs in the `npm` environment, which
+only `main` can deploy to, and npm's trusted publisher names that environment and
+`npm-publish.yml`. A deliberate major or minor bump in a PR is kept. Runs never overlap,
+and when merges land together only the newest pending run starts, so intermediate
+versions can be skipped on npm.
+
+The workflow installs, typechecks, runs the package suite (`bun run check:package`) in the
+runner's Google Chrome, and packs the tarball, all without publish rights; the publish job
+receives only that tarball and runs `npm publish --ignore-scripts`. The merged commit has
+already passed the full `bun run check`.
+
+npm adds a trusted publisher only to a package that already exists, so the first version
+is published by hand from an up-to-date `main`. Until then the workflow fails with that
+instruction rather than attempting a publish npm would reject:
+
+```sh
+npm login
+npm publish   # prepublishOnly runs bun run check; prepack builds lib/ and site/
+```
+
+Then, in the package's settings on npmjs.com, add a GitHub Actions trusted publisher for
+repository `a2f0/skyline`, workflow `npm-publish.yml`, and environment `npm`, and re-run
+the workflow; it reports the version as already published.
+
+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
+[NOTICE.md](../NOTICE.md). The standalone site's `bun run build:site` and Cloudflare
+deployment flow remain separate from packaging.