@ue-shed/protocol 0.7.0 → 0.8.0

package/contracts/cameras/review/v1/fixtures/capture-authored.json

@@ -0,0 +1,205 @@
+{
+	"authoredVisibility": {
+		"version": 1,
+		"output": "natural_and_authored",
+		"actors": {
+			"hide": [],
+			"protect": []
+		}
+	},
+	"authoredEvidence": {
+		"visibilityDiagnostics": [],
+		"editorState": {
+			"mapPackageDirtyBefore": false,
+			"mapPackageDirtyAfter": false
+		},
+		"camera": {
+			"location": {
+				"x": 950,
+				"y": -750,
+				"z": 650
+			},
+			"rotation": {
+				"pitch": -25.000000000000007,
+				"roll": -1.754676902789813e-15,
+				"yaw": 140
+			},
+			"projection": {
+				"kind": "perspective",
+				"horizontalFieldOfView": 40
+			}
+		},
+		"size": {
+			"width": 640,
+			"height": 360
+		},
+		"policy": {
+			"visibility": {
+				"hide": [],
+				"protect": []
+			},
+			"renderer": {
+				"kind": "scene_capture",
+				"profile": "scene_capture_defaults",
+				"lodDistanceScale": 1,
+				"fog": true,
+				"volumetricFog": true
+			},
+			"exposure": {
+				"mode": "fixed_ev100",
+				"ev100": 10,
+				"compensation": "project"
+			},
+			"settling": {
+				"minimumFrames": 1,
+				"timeoutMs": 120000
+			},
+			"time": "live_editor",
+			"preparation": {
+				"geometry": {
+					"mode": "preserve_loading"
+				},
+				"dataLayers": []
+			}
+		},
+		"exposureEV100": 10,
+		"preparation": {
+			"status": "preserved",
+			"regionsHeld": 0,
+			"dataLayersApplied": 0,
+			"limitations": [
+				"Explicit editor loading does not certify frustum completeness, shader convergence, or gameplay initialization."
+			]
+		},
+		"settling": {
+			"renderedFrames": 1,
+			"elapsedMs": 36.709997802972794,
+			"convergence": "not_assessed"
+		},
+		"engineVersion": "5.7.4-51494982+++UE5+Release-5.7",
+		"pluginVersion": "0.7.1"
+	},
+	"renderEvidence": {
+		"editorState": {
+			"mapPackageDirtyBefore": false,
+			"mapPackageDirtyAfter": false
+		},
+		"camera": {
+			"location": {
+				"x": 950,
+				"y": -750,
+				"z": 650
+			},
+			"rotation": {
+				"pitch": -25.000000000000007,
+				"roll": -1.754676902789813e-15,
+				"yaw": 140
+			},
+			"projection": {
+				"kind": "perspective",
+				"horizontalFieldOfView": 40
+			}
+		},
+		"size": {
+			"width": 640,
+			"height": 360
+		},
+		"policy": {
+			"renderer": {
+				"kind": "scene_capture",
+				"profile": "scene_capture_defaults",
+				"lodDistanceScale": 1,
+				"fog": true,
+				"volumetricFog": true
+			},
+			"exposure": {
+				"mode": "fixed_ev100",
+				"ev100": 10,
+				"compensation": "project"
+			},
+			"settling": {
+				"minimumFrames": 1,
+				"timeoutMs": 120000
+			},
+			"time": "live_editor",
+			"preparation": {
+				"geometry": {
+					"mode": "preserve_loading"
+				},
+				"dataLayers": []
+			}
+		},
+		"exposureEV100": 10,
+		"preparation": {
+			"status": "preserved",
+			"regionsHeld": 0,
+			"dataLayersApplied": 0,
+			"limitations": [
+				"Explicit editor loading does not certify frustum completeness, shader convergence, or gameplay initialization."
+			]
+		},
+		"settling": {
+			"renderedFrames": 1,
+			"elapsedMs": 47.80590161681175,
+			"convergence": "not_assessed"
+		},
+		"engineVersion": "5.7.4-51494982+++UE5+Release-5.7",
+		"pluginVersion": "0.7.1"
+	},
+	"captureDurationMs": 84.51589941978455,
+	"clearCompanion": {
+		"status": "not_requested"
+	},
+	"contract": {
+		"name": "ue-shed-review-capture",
+		"version": {
+			"major": 1,
+			"minor": 7
+		}
+	},
+	"effectiveWorldPose": {
+		"aspectRatio": "16:9",
+		"fieldOfViewDegrees": 40,
+		"location": {
+			"x": 950,
+			"y": -750,
+			"z": 650
+		},
+		"projection": "perspective",
+		"rotation": {
+			"pitch": -25.000000000000007,
+			"roll": -1.754676902789813e-15,
+			"yaw": 140
+		}
+	},
+	"height": 360,
+	"mapPackageDirtyAfter": false,
+	"mapPackageDirtyBefore": false,
+	"mapPath": "/Game/Fixture",
+	"operationId": "49cebd79-1a5a-460d-aab8-17a89c29644e",
+	"resolvedSubject": {
+		"kind": "unresolved_actor",
+		"subject": {
+			"actorPath": "/Game/Fixture.Fixture:PersistentLevel.Floor",
+			"kind": "actor_path"
+		},
+		"reason": "World-fixed capture does not require subject realization."
+	},
+	"stagedArtifacts": [
+		{
+			"stagingPath": "Saved/UEShed/CameraRenderStaging/fc6528fe-c1e9-4bcf-bff5-c8e06c98bfa2/pure.png",
+			"variant": "pure"
+		},
+		{
+			"stagingPath": "Saved/UEShed/CameraRenderStaging/a50b0ff7-e587-43a9-bc68-da84deb947b7/authored.png",
+			"variant": "authored"
+		}
+	],
+	"status": "captured",
+	"viewId": "view-a",
+	"visibility": {
+		"reason": "Actor unavailable in the loaded editor world; the independent camera was rendered.",
+		"status": "not_assessed"
+	},
+	"width": 640
+}

package/contracts/core/v1/WINDOW-ACTIVATION.md

@@ -0,0 +1,21 @@
+# Editor window activation
+
+`UEShedCoreEditor` advertises `editor.window-activation.v1` and a
+`windowActivationObjectPath` in the Core capability manifest. Invoke `ActivateEditorWindow`
+there with `RequestJson` matching `window-activation-request.schema.json`; decode `ResultJson`
+with `window-activation-result.schema.json`.
+
+Use the manifest's process identity as `expectedProcessId`. The companion rejects stale identities.
+It targets its main editor window, or the active modal dialog that must be handled first. It does
+not select actors, move cameras, open maps, dismiss dialogs, save packages, or launch an editor.
+
+On Windows, activation restores a minimized main window and calls `SetForegroundWindow`, then
+checks the actual foreground window. A denied request returns `blocked`; a missing window returns
+`unavailable`. Unsupported platforms return `unsupported`. An actor-navigation success is not a
+window-activation success.
+
+For a local endpoint, a foreground client can first grant permission to this one process using
+`AllowSetForegroundWindow`. The engine package supplies this through its optional Windows native
+helper. It never grants `ASFW_ANY`, attaches input queues, simulates keyboard input, changes focus
+lock settings, or performs automatic focus retries. Remote endpoints do not receive local grants.
+Call only for an explicit user handoff; observation and background follow ticks must not activate.

package/contracts/core/v1/window-activation-request.schema.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$defs": {},
+	"type": "object",
+	"properties": {
+		"expectedProcessId": {
+			"type": "integer",
+			"allOf": [
+				{
+					"exclusiveMinimum": 0
+				},
+				{
+					"exclusiveMaximum": 4294967295
+				}
+			]
+		}
+	},
+	"required": ["expectedProcessId"],
+	"additionalProperties": false
+}

package/contracts/core/v1/window-activation-result.schema.json

@@ -0,0 +1,49 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$defs": {},
+	"type": "object",
+	"properties": {
+		"schemaVersion": {
+			"type": "number",
+			"enum": [1]
+		},
+		"processId": {
+			"type": "integer",
+			"allOf": [
+				{
+					"exclusiveMinimum": 0
+				},
+				{
+					"exclusiveMaximum": 4294967295
+				}
+			]
+		},
+		"status": {
+			"type": "string",
+			"enum": ["activated", "blocked", "unavailable", "unsupported", "target_changed"]
+		},
+		"target": {
+			"type": "string",
+			"enum": ["main_editor", "modal", "none"]
+		},
+		"restored": {
+			"type": "boolean"
+		},
+		"message": {
+			"type": "string"
+		},
+		"recovery": {
+			"type": "string"
+		}
+	},
+	"required": [
+		"schemaVersion",
+		"processId",
+		"status",
+		"target",
+		"restored",
+		"message",
+		"recovery"
+	],
+	"additionalProperties": false
+}

package/contracts/editor-world/v1/README.md

@@ -8,3 +8,30 @@ packages, missing maps, and failed loads as typed outcomes.
 `request.schema.json` and `response.schema.json` are the language-neutral authority shared by
 `@ue-shed/protocol` and `UEShedCoreEditor`. The companion advertises
 `editor.world-control.v1` and its reflected object path before clients may invoke the operation.
+
+## Asynchronous opening and live state
+
+Companions advertising `editor.world-control.async.v1` accept the same explicit request via
+`BeginOpenMap`. It returns an `operation.schema.json` acknowledgement before scheduling the actual
+load on the game thread. `GetOpenMapStatus` takes that same request identity and is read-only.
+`pending` and `running` are not successful loads; `completed.result` contains the original typed
+open/refusal response. Dirty-world and play-session checks run immediately before loading.
+
+There is at most one pending/running operation. Repeating an identity returns its retained state,
+and using it for another target reports `conflict`. The producer retains the last 32 terminal
+operations in process memory. An unknown/evicted identity or editor restart reports
+`unknown_operation`; clients must not reinterpret it as permission to replay a mutation.
+
+Unreal's map loader still blocks its game thread. Status requests can time out during a large load;
+clients retry only these read-only queries. There is no invented progress percentage and no remote
+cancel/discard capability. The public engine workflow waits up to 30 minutes by default (configurable
+per call), checks deadlines between bounded requests, and reports an indeterminate outcome on expiry.
+Interrupting a client wait stops its polling, not Unreal's already accepted operation. Old companions
+retain the synchronous API with a longer request budget and no automatic retry.
+
+`editor.world-state.v1` advertises `GetWorldState`, returning `state.schema.json`: the current editor
+map, dirty world packages, project name and whether Play/Simulate is active. Updated companions also
+return `projectRoot`, the absolute project directory. It is optional for wire compatibility; clients
+that require a matching local project must reject missing or mismatched identity rather than infer
+it from a map path or display name. Clients can poll state independently of camera or actor streams.
+No editor-event subscription is claimed by this version.