Add Director authoring, import previews and scene bundles

docs/CURRENT-STATE.md

@@ -1,5 +1,12 @@
 # God's Eye View Current State
 
+Director imports now open a non-mutating preview before Apply. EDIT DETAILS
+authors validated anchor, camera, pack and interaction drafts; SHARE SCENE exports
+a selected scene or a bounded bundle of explicitly chosen pack files. Bundled
+bytes remain in memory until replacement/teardown and require reimport after a
+page reload. Stop releases rendering while retaining replay bytes. Cancellation
+and stale drafts cannot replace newer project state. See [authoring and sharing](DIRECTOR-SHARING.md).
+
 Director version-6 documents add bounded, scene-local feature actions. Settled
 LOAD/seek exposes keyboard-accessible text/source cards, anchor focus, explicit
 shot transitions and admitted layer state changes. Pointer claims take priority;
@@ -48,9 +55,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 5 is the export format, with
+are protected from fallback writes. Version 6 is the export format, with
 zero pitch, low camera heights, scope and detection edits preserved. See [the document contract](SCENE-DOCUMENT.md);
-interactions remain planned in [Director](DIRECTOR.md).
+see [Director](DIRECTOR.md) for camera, pack, action and sharing support.
 
 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-CAMERA.md

@@ -3,7 +3,8 @@
 Version 4 scene documents can name geographic anchors and describe an explicit
 camera move followed by a hold. Existing camera-pose shots still use the ordinary
 camera flight. Import, playback, Load, Replay and seek accept the new directions;
-a visual anchor/path editor is a later authoring step.
+[EDIT DETAILS](DIRECTOR-SHARING.md) captures anchors and move starts; a graphical
+path editor remains a later extension.
 
 ```json
 {

docs/DIRECTOR-DATA-PACKS.md

@@ -74,7 +74,8 @@ 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.
+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
 
@@ -110,5 +111,5 @@ 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.
+See [actions](DIRECTOR-INTERACTIONS.md) and [authoring/sharing](DIRECTOR-SHARING.md)
+for the controls built on this manifest/loading boundary.

docs/DIRECTOR-INTERACTIONS.md

@@ -62,6 +62,5 @@ interaction owner supplies accessible DOM and picking; pack renderers own the
 feature identities and release them with their geometry. Layer/source admission
 and camera arbitration remain with their existing owners.
 
-Visual authoring, import previews and share bundles remain separate follow-up
-work. For now, author actions in scene JSON and use the existing import/export
-controls. Existing content, assets, notices and contributor credit are preserved.
+Author actions in scene JSON or the validated EDIT DETAILS draft.
+[Import preview and file sharing](DIRECTOR-SHARING.md) preserve those declarations. Existing content, assets, notices and contributor credit are preserved.

docs/DIRECTOR-SHARING.md

@@ -0,0 +1,96 @@
+# Director authoring and file sharing
+
+Open Scenes and select a scene and shot. Existing capture, update, playback and
+whole-project export controls remain available. Authored scene content, source
+links, assets and contributor credit are preserved.
+
+## Review imports before applying
+
+IMPORT accepts scene JSON (including older supported versions) or a
+`.gevbundle.json` asset bundle. A preview lists scenes, shots, data-pack attribution,
+configured or unavailable sources, missing layer IDs and bundled bytes. Preview
+makes no asset requests and does not change the current project. Configured
+sources do not guarantee that a file exists: ordinary assets are checked on LOAD.
+Bundle preview verifies the manifest and byte integrity; format decoding and
+geometry limits are still enforced when rendering.
+
+Apply replaces the current project after validation and playback cleanup. Export
+your current project first if you want to keep both. Cancel or Escape discards
+the staged import. A changed project invalidates an open draft rather than being
+overwritten. Invalid files leave the existing project and browser save intact.
+The programmatic `importProjectFile(file)` API still applies trusted callers'
+imports directly; the installed file chooser supplies the review step.
+
+## Edit scene details
+
+EDIT DETAILS provides validated JSON fields for:
+
+- Scene anchors and data-pack manifests.
+- The selected shot's camera, optional move, duration, hold, pack IDs and actions.
+
+Capture camera as anchor adds a named geographic position to the draft. Set move
+start to current camera creates a pose-to-pose move ending at the shot's existing
+camera; Use ordinary flight removes that explicit move. Heights are meters above
+the WGS84 ellipsoid. Apply details validates the complete project, preserves IDs,
+layer declarations and content notices, and keeps the selected shot. Cancel
+leaves the project unchanged. See [camera directions](DIRECTOR-CAMERA.md),
+[data packs](DIRECTOR-DATA-PACKS.md) and [actions](DIRECTOR-INTERACTIONS.md) for
+field definitions. This is a basic draft editor, not a node graph or path editor.
+
+## Share a selected scene
+
+SHARE SCENE exports only the selected scene. Download scene JSON preserves its
+camera, timing, layers, anchors, manifests, interactions and attribution, but
+contains no asset bytes. The recipient needs the referenced source registrations
+and files. Existing EXPORT PRESETS continues to export the entire project.
+
+For a bundle, select the declared pack files or a folder, then Download asset
+bundle. Folder paths match a manifest path either directly or after removing the
+chosen root directory. Individual filenames must be unambiguous across all pack
+sources; ambiguous or missing matches fail without downloading a partial bundle.
+Previously imported bundle files can be reused. Export never automatically fetches
+remote files or copies registered recipe media. Existing integrity declarations
+must match the files you supply.
+
+Bundles include only declared data-pack files. Registered scene content, linked
+media, map tiles and live data are not included. Source notices and licenses remain
+in the document; packaging a file does not grant permission to redistribute it.
+
+## Bundle format and limits
+
+A bundle is uncompressed JSON with these fields:
+
+```json
+{
+  "format": "gev-scene-bundle",
+  "version": 1,
+  "project": { "version": 6, "scenes": [] },
+  "assets": []
+}
+```
+
+Each asset contains `path`, `mimeType`, `base64` and lowercase hexadecimal `sha256`.
+Export copies the document and rewrites pack references to the reserved
+`scene-bundle` source, adding exact `byteLength` and `sha256`. Paths are confined
+relative names; URLs, traversal, duplicate or unreferenced assets, unknown fields,
+missing packs and mismatched hashes are rejected. Scene documents remain bounded
+at 5 MiB. A bundle allows 50 MiB of JSON, 64 files, 8 MiB per file and 32 MiB of
+asset bytes in total. Supported MIME types are JSON/GeoJSON, PNG, MP4/WebM video
+and MPEG/Ogg/WAV/WebM audio. Normal pack format and geometry checks still apply.
+There are no executable modules, request headers or credentials in the format.
+
+Imported bytes stay in memory for the current project and session. Stop releases
+rendered resources while retaining these bytes for replay. Project replacement
+or application teardown releases them. Only scene JSON is saved in browser
+storage: **reimport the bundle after reloading the app**. Missing bundle bytes
+fail explicitly, with no network fallback. This is file sharing, not a storage
+service or an offline basemap.
+
+Portable helpers are exported through `gods-eye-view/director`: `parseSceneShare`,
+`readSceneShare`, `createSceneBundle`, `createBundleAssets`, `describeSceneShare`,
+`editSceneDetails` and `selectSceneDocument`. Loading and UI remain separate owners.
+`getSharingState()` reports copied dialog/asset counts for lifecycle diagnostics.
+
+Run `node scripts/qa-director-sharing.mjs` against the local server for installed
+controls, cancellation, stale drafts, export/import round trips, resource cleanup
+and narrow-screen acceptance. Fixtures are synthetic and carry their own notices.

docs/DIRECTOR.md

@@ -2,8 +2,8 @@
 
 Director is the scene playback system. Ordered shot execution, authored timing and playback clocks are separated
 from the scene editor and application rendering. This document
-also records the proposed next steps; the sharing format and interactions below
-are a design plan, not features already available.
+records implemented camera directions, data packs, declarative interactions and
+file sharing, along with the remaining extensions.
 
 ## Implemented boundary
 
@@ -76,8 +76,8 @@ and river coordinates are bundled. See the
    [Version 4](DIRECTOR-CAMERA.md) adds scene-local geographic anchors, explicit
    start/destination poses, easing, duration and holds. Playback and seek share
    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.
+   is rejected. Existing shots retain ordinary flights. Basic anchor/move authoring is available through EDIT DETAILS; curved paths and
+   look-at targets remain later extensions.
 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
@@ -85,20 +85,19 @@ and river coordinates are bundled. See the
    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,
-   keyboard equivalents and precedence with drawing/tracking controls. Validate
-   target references and cancel pending actions on Stop, replacement or teardown.
-   No JavaScript evaluation or arbitrary HTML in scene files. Branching must
-   have explicit loop/transition limits and reproducible reset/seek semantics.
-6. **Sharing and authoring.** Add validated preview/import/export, missing-pack
-   diagnostics and an optional self-contained bundle. Preserve attribution with
-   each pack; a share link does not change an asset's license. A future node graph
-   could author this same document, but playback and the format will not require
-   a graph editor.
+   explicitly. File bundles are available; transforms and terrain-relative placement
+   remain future extensions. Scene files carry no credentials or executable modules.
+5. **Declarative interactions — implemented.** [Version 6](DIRECTOR-INTERACTIONS.md)
+   connects selected feature IDs to accessible text/source cards, anchor focus,
+   shot seek and admitted layer changes. References are validated and pending
+   actions cancel on Stop, replacement or teardown. Scene files contain no
+   JavaScript or arbitrary HTML; actions require explicit user input.
+6. **Sharing and basic authoring — implemented.** [Authoring and sharing](DIRECTOR-SHARING.md)
+   adds import preview, missing-source/layer diagnostics, validated scene/shot
+   drafts and selected-scene JSON or explicit-file bundles. Pack attribution is
+   preserved. Bundle bytes last for the session and must be reimported after a
+   reload. A future node graph can author the same document without becoming a
+   playback or format requirement.
 
 Each step must preserve existing scene editing, keyboard playback, camera
 arbitration, layer cleanup, media timing and provider fallback. Acceptance includes