mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
Move the page handoff sequence into SceneSwitcher and include restoration in the application's candidate attachment. Release a failed candidate once before the request coordinator recovers the working engine. Keep address ordering, parked renderers, retained layers and cockpit resumption intact. Define the layer session and its field owners. Share its retention decision across teardown paths. Separate layer scene binding from lifecycle policy, and shell scene composition from page controls. Keep failed renderer releases in the binding owner, with the existing retry behavior. Give Director the scene and use the engine host for its canvas and pack container. Keep the existing tracked-subject interaction guard so neither engine's behavior changes. Pass startup chrome the first backend's explicit welcome policy instead of testing for a viewer. Cesium remains the behavior reference; this restructuring intentionally changes no visible behavior on either engine. Viewer references outside the Cesium engine fall from 948 to 933. All other coupling counts stay unchanged. Scene service ownership, raw debug access, and the remaining shell and host queues still need consolidation. Checked in the browser, keyless, on the dev server: the engine switch, Director engine switch, layer panel and layer visibility on both engines pass, and 14 of 15 strict scenarios pass (rapid, hidden-tab, context-loss, parked-release, Navara HD, failure matrix and soak among them). app-once and the Director next-shot step fail the same way before this change.
116 lines
6.2 KiB
Markdown
116 lines
6.2 KiB
Markdown
# 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 and archive extraction are not implemented. Explicit local files
|
||
can be shared through [JSON asset bundles](DIRECTOR-SHARING.md).
|
||
|
||
## 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(scene, 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.
|
||
See [actions](DIRECTOR-INTERACTIONS.md) and [authoring/sharing](DIRECTOR-SHARING.md)
|
||
for the controls built on this manifest/loading boundary.
|