feat(director): add bounded scene data packs and placement

docs/CURRENT-STATE.md

@@ -1,5 +1,12 @@
 # God's Eye View Current State
 
+Director version-5 documents add scene-local data-pack manifests and per-shot
+selection. Registered sources acquire bounded, cancellable assets separately from
+GeoJSON, PNG and manually played media presentation. Storage paths, attribution
+and geographic placement remain distinct; Stop/replacement releases resources.
+Import acquires nothing. See [data packs](DIRECTOR-DATA-PACKS.md). Existing scene
+content, assets and credit remain unchanged.
+
 Director version-4 documents add named geographic anchors and optional explicit
 camera moves with easing, duration and holds. Playback and seek share one
 coordinate sampler; navigation/manual input revokes authored motion and pending
@@ -34,9 +41,9 @@ holds; stale tick callbacks cannot publish into a replacement. Registered pack
 rules own presentation overrides and Nepal map fallback without changing saved
 shots or content. Scene-document validation and legacy migration now have separate
 owners. Invalid imports preserve the current project; unreadable saved projects
-are protected from fallback writes. Version 4 is the export format, with
+are protected from fallback writes. Version 5 is the export format, with
 zero pitch, low camera heights, scope and detection edits preserved. See [the document contract](SCENE-DOCUMENT.md);
-data packs and interactions remain planned in [Director](DIRECTOR.md).
+interactions remain planned in [Director](DIRECTOR.md).
 
 Search framing and annotations request semantic map features from an explicit source. The Overpass adapter owns bounded queries, member/tag decoding and request deadlines; callers retain candidate ranking, outline caching, deferred retries and scene placement. Empty, transient and throttled outcomes remain distinct. Traffic sources return road records and installation sources return mapped records with freshness/saturation metadata, so their layers no longer decode upstream elements. ALPR already normalizes its records in the source. Default providers, footprints, road directions, exact-viewport retries and source attribution are unchanged.
 

docs/DIRECTOR-DATA-PACKS.md

@@ -0,0 +1,114 @@
+# Director data packs
+
+Version-5 scene documents can declare `dataPacks` on a scene and select them by
+`dataPackIds` on each shot. Import validates declarations without loading assets.
+Loading, seeking or playing a shot acquires only its selected packs. A shot with
+no pack IDs clears the preceding shot's packs. Existing scene recipes and assets
+keep their current paths, notices and behavior.
+
+A pack manifest is version 1 and requires an ID, format, source, attribution and
+placement. Sources describe storage; placement describes geography. Source names
+refer to trusted application registrations, never scripts to import. A document
+cannot supply request headers, keys, cookies, endpoints or executable handlers.
+
+```json
+{
+  "version": 5,
+  "scenes": [{
+    "id": "example",
+    "title": "My geographic notes",
+    "dataPacks": [{
+      "id": "notes",
+      "version": 1,
+      "format": "geojson",
+      "source": { "adapter": "assets", "path": "my-scene/notes.geojson" },
+      "attribution": { "text": "Your name", "license": "Your asset's actual license" },
+      "placement": { "altitudeReference": "ellipsoid" }
+    }],
+    "shots": [{
+      "id": "overview",
+      "camera": { "lat": 30.2672, "lon": -97.742, "alt": 2600, "pitch": -70 },
+      "durationSec": 4,
+      "holdSec": 2,
+      "dataPackIds": ["notes"]
+    }]
+  }]
+}
+```
+
+For the standalone application, put that asset at
+`public/scene-assets/my-scene/notes.geojson`. The registered `assets` source has
+an explicit `/scene-assets/` base on the application's origin. Importing a file
+from disk does not grant access to adjacent local files or infer a remote base.
+Relative paths cannot contain traversal, query strings, fragments, URL syntax,
+percent escapes or empty segments. Asset directories are served as static files;
+this is not a new arbitrary-URL proxy.
+
+## Formats and placement
+
+- **`geojson`:** a UTF-8 `FeatureCollection`, served as `application/geo+json` or
+  `application/json`. Each feature needs a unique string `id`. Point, LineString
+  and Polygon (including holes) are supported. Coordinates are WGS84
+  `[longitude, latitude, ellipsoidHeightMeters]`; missing height means zero,
+  which can be underground. Supply appropriate heights. Geometry properties
+  are ignored: they cannot select external icons, HTML, styling or scripts.
+  Placement is `{ "altitudeReference": "ellipsoid" }`.
+- **`image`:** PNG served as `image/png`, at most 4096×4096 pixels, checked before
+  decoding. Placement is `{ "bounds": [west, south, east, north], "height": 300,
+  "altitudeReference": "ellipsoid" }`. Bounds must increase and cannot cross
+  the dateline. The image is a horizontal geographic rectangle at that height.
+- **`media`:** MP4/WebM video or MPEG/Ogg/WAV/WebM audio, with the matching standard
+  MIME type. Placement is `{ "anchorId": "media-location" }`, referring to a
+  scene-local anchor with explicit ellipsoid height. A labelled marker locates
+  the media; an attribution card provides native, user-operated playback
+  controls. Media never autoplays. Codec support depends on the browser. D5 does
+  not synchronize media time with scene time or embed third-party players.
+
+Pack attribution always includes nonempty `text` and `license`; an optional
+HTTPS `url` opens as a source link with no opener/referrer. Importing or sharing
+an asset never changes its license. D5 adds no third-party content and preserves
+all existing Nepal content and contributor notices.
+
+Optional `byteLength` specifies the exact expected byte count; optional `sha256`
+is a lowercase hexadecimal SHA-256 digest checked before rendering. There are at
+most 8 packs per scene, 8 MiB per asset, and 32 MiB of selected assets per shot.
+GeoJSON additionally allows at most 2,000 features and 50,000 positions.
+Transforms, terrain-relative placement, terrain collision avoidance, arbitrary
+GeoJSON styles, archives and local filesystem bundles are not implemented.
+
+## Loading and resource ownership
+
+The `director` package export provides `createAssetDirectorySource` and
+`createDataPackSession`. The former receives an explicit trusted HTTP(S)
+directory `baseUrl` and optional `fetchImpl`; it confines every relative asset
+path to that directory. Cross-origin directories require CORS. Requests omit
+credentials and referrers, reject redirects, and use `cache: 'no-store'`.
+There is no persistent pack cache, offline fallback or silent substitute. A
+missing, invalid, oversized or integrity-mismatched asset fails the shot's pack
+load, removes partial results and reports a stable error without exposing a URL.
+Successful loading leaves the attribution cards visible with the assets.
+
+`createApplicationTools({ sceneDataPacks: { sources } })` and
+`new SceneDirector(viewer, style, data, { dataPacks: { sources } })` accept a
+registry of source functions. Each receives `{ path, signal, maxBytes }` and
+returns `{ bytes: Uint8Array, mimeType }`. Custom transports must honor the
+signal, bound reads and return the real MIME type. They remain application code,
+not scene document fields. Without registrations, referenced sources fail closed.
+
+The portable session receives format adapters separately. Each adapter receives
+`{ pack, asset, anchors, signal }` and returns a resource with an idempotent
+`dispose()`. Core's scene composition supplies Cesium geometry/image rendering
+and text-only attribution/native media controls. The session applies a 15-second
+load deadline and rejects late results, even when an adapter ignores abort.
+
+Stop, replacement, next-shot selection, scene release and destruction cancel
+pending work, remove owned entities/cards, stop media and revoke object URLs.
+Run completion releases packs with its run signal. Direct LOAD and seek retain
+packs until the next operation or Stop. Resources are reacquired per shot;
+there are no disabled pack refresh loops. `getDataPackState()` returns copied
+status and resource counts for lifecycle diagnostics.
+
+Run `node scripts/qa-director-packs.mjs` against a credentialed local server to
+exercise the real import/load/seek/Stop path with self-authored synthetic assets.
+This stage provides the manifest/loading boundary; interactive actions and
+visual authoring follow separately.

docs/DIRECTOR.md

@@ -78,14 +78,15 @@ and river coordinates are bundled. See the
    the same sampler. Ellipsoidal heights are explicit; terrain-relative input
    is rejected. Existing shots retain ordinary flights. Curved paths, look-at
    targets and visual authoring are later extensions.
-4. **Data packs and placement.** Define a pack manifest with format/version,
-   source, attribution/license and optional integrity/size metadata. Distinguish
-   where bytes live (relative files, a URL, or an eventual bundle) from where
-   features appear (geographic bounds, anchors, transforms and elevation rules).
-   Start with existing GeoJSON/image/media adapters. Resolve relative paths
-   against an explicit document base; define CORS, caching, missing-asset and
-   offline behavior. Fetch only through registered source adapters with bounded,
-   cancellable loading. Scene files carry no credentials or executable modules.
+4. **Data packs and placement — implemented for bounded assets.**
+   [Version 5](DIRECTOR-DATA-PACKS.md) defines a pack manifest with format/version,
+   source, attribution/license and optional integrity/size metadata. It distinguishes
+   registered asset directories from geographic coordinates, image bounds and
+   media anchors. GeoJSON, PNG and native media adapters load with byte/time
+   limits and explicit ellipsoid heights. Stop and replacement release resources.
+   Paths resolve against a trusted directory base; missing/offline assets fail
+   explicitly. Bundles, transforms and terrain-relative placement remain future
+   extensions. Scene files carry no credentials or executable modules.
 5. **Declarative interactions.** Give pickable features stable IDs and connect
    clicks to a small action registry: show a text/source card, focus an anchor,
    seek a shot, or change an allowed layer state. Define selection feedback,

docs/SCENE-DOCUMENT.md

@@ -1,13 +1,13 @@
 # Scene document format
 
-Scenes exports a UTF-8 JSON project. Version 4 adds [camera directions](DIRECTOR-CAMERA.md)
-and is the write format. Versions 1, 2, 3 and unversioned legacy files migrate on
+Scenes exports a UTF-8 JSON project. Version 5 adds [data packs](DIRECTOR-DATA-PACKS.md)
+and is the write format. Versions 1, 2, 3, 4 and unversioned legacy files migrate on
 import without converting their existing shots into authored moves. Unknown versions or unsupported fields are rejected with
 a field path before the current project, selection or saved bytes change.
 
 ```json
 {
-  "version": 4,
+  "version": 5,
   "scenes": [{
     "id": "my-scene",
     "title": "My scene",
@@ -95,7 +95,11 @@ can preserve temporary edits. Storage writes use the same validation before repl
 edits and storage write failures surface an unsaved toast.
 
 Only authored project fields belong in this file. Runtime clocks, camera flights,
-loading progress and run diagnostics remain separate. Version 4 supports scene-local camera anchors and authored moves. Asset-pack
-manifests and declarative interactions remain planned extensions. They will
-receive stable IDs and their own validated migration when introduced. No scene assets, source links, licenses or contributor attribution
+loading progress and run diagnostics remain separate. Camera anchors and authored
+moves arrived in version 4; data packs follow in version 5. Declarative
+interactions remain a planned extension. No scene assets, source links, licenses or contributor attribution
 change with this document boundary.
+
+Version 5 additionally accepts scene `dataPacks` and shot `dataPackIds`, as
+defined in [data packs](DIRECTOR-DATA-PACKS.md). Version-4 camera documents
+continue to import without adding any packs.