marionette 5.0.0-beta.4 → 5.0.0-beta.5

package/changelog.md

@@ -1,3 +1,25 @@
+### v5.0.0-beta.5
+
+> An Application can keep its children without keeping yesterday’s living room.
+
+* Separate Application root ownership from its host Region. Stopping an Application
+  releases its prepared and displayed roots without clearing another Application's
+  replacement in a borrowed Region. Prepare roots with `setView()` and hand them
+  to the Region with `showView()`; displaying a View directly through a Region
+  does not transfer Application ownership.
+* Accept an existing Region in `start({ region })` and `restart({ region })`, so
+  retained child Applications can follow recreated parent layouts. Constructor
+  Region definitions remain owned; startup Regions are borrowed. Use `restart()`
+  when changing the host of an active Application.
+* Add `childApps` constructor maps or functions for static, no-argument children.
+  Construct and register them once before parent initialization; activation stays
+  explicit. Subclass and option declarations replace inherited maps. Use
+  `addChildApp()` for dynamic children or constructor arguments.
+* Expand executable lifecycle and migration guidance, and direct documentation
+  retrieval toward relevant contracts. These changes do not establish measured
+  agent-effectiveness or stable-v5 readiness.
+* Shard Windows release certification while retaining the complete fixture gate.
+
 ### v5.0.0-beta.4
 
 > Events announce. Preparation waits. Apparently those needed separate job descriptions.

package/dist/docs/config/api-contracts/inventory.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "authority": "authored TypeScript and explicit public behavioral evidence",
-  "semanticsSha256": "0929a305cce177355389fafdc1c5b46d8332046647ce7c970b27b49be866c616",
+  "semanticsSha256": "077157bce1349db05f4e0870f4c4bce89077b3b0d227da7ec485034388c79074",
   "entrypoints": [
     {
       "name": "marionette",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "src/index.ts",
       "conditions": {
@@ -56,6 +56,7 @@
             "bindEvents": "<Receiver extends Listener>(this: Receiver, entity?: false | \"\" | 0 | 0n | EventSource | null | undefined, bindings?: false | object | \"\" | 0 | 0n | null | undefined) => Receiver",
             "bindRequests": "<Receiver>(this: Receiver, channel?: false | \"\" | 0 | 0n | ReplyChannel | null | undefined, bindings?: false | object | \"\" | 0 | 0n | null | undefined) => Receiver",
             "channelName": "?string | (() => string) | undefined",
+            "childApps": "?ChildApplications | (() => ChildApplications) | undefined",
             "cid": "string",
             "cidPrefix": "string",
             "createState": "(options?: (object & ApplicationOptions) | undefined) => unknown",
@@ -96,10 +97,10 @@
             "region": "?RegionDefinition | undefined",
             "regionClass": "RegionClass",
             "removeChildApp": "(name: string, options?: unknown) => Promise<ApplicationInstance<object, unknown, unknown> | undefined>",
-            "restart": "(options?: unknown) => Promise<boolean>",
+            "restart": "(options?: ApplicationStartOptions | undefined) => Promise<boolean>",
             "setView": "<Child extends SupportedView>(view: Child) => Child",
             "showView": "{ (view?: undefined, options?: ShowOptions | undefined): SupportedView | undefined; <Child extends SupportedView>(view: Child, options?: ShowOptions | undefined): Child; }",
-            "start": "(options?: unknown) => Promise<boolean>",
+            "start": "(options?: ApplicationStartOptions | undefined) => Promise<boolean>",
             "state": "?unknown",
             "State": "Partial<StateApi<never>>",
             "stateEvents": "?object | (() => object) | undefined",
@@ -354,6 +355,7 @@
             "bindEvents": "<Receiver extends Listener>(this: Receiver, entity?: false | \"\" | 0 | 0n | EventSource | null | undefined, bindings?: false | object | \"\" | 0 | 0n | null | undefined) => Receiver",
             "bindRequests": "<Receiver>(this: Receiver, channel?: false | \"\" | 0 | 0n | ReplyChannel | null | undefined, bindings?: false | object | \"\" | 0 | 0n | null | undefined) => Receiver",
             "channelName": "?string | (() => string) | undefined",
+            "childApps": "?ChildApplications | (() => ChildApplications) | undefined",
             "cid": "string",
             "cidPrefix": "string",
             "createState": "(options?: Options | undefined) => unknown",
@@ -394,10 +396,10 @@
             "region": "?RegionDefinition | undefined",
             "regionClass": "RegionClass",
             "removeChildApp": "(name: string, options?: unknown) => Promise<ApplicationInstance<object, unknown, unknown> | undefined>",
-            "restart": "(options?: unknown) => Promise<boolean>",
+            "restart": "(options?: ApplicationStartOptions | undefined) => Promise<boolean>",
             "setView": "<Child extends SupportedView>(view: Child) => Child",
             "showView": "{ (view?: undefined, options?: ShowOptions | undefined): SupportedView | undefined; <Child extends SupportedView>(view: Child, options?: ShowOptions | undefined): Child; }",
-            "start": "(options?: unknown) => Promise<boolean>",
+            "start": "(options?: ApplicationStartOptions | undefined) => Promise<boolean>",
             "state": "?unknown",
             "State": "Partial<StateApi<never>>",
             "stateEvents": "?object | (() => object) | undefined",
@@ -604,6 +606,7 @@
           ],
           "members": {
             "channelName": "?string | (() => string) | undefined",
+            "childApps": "?ChildApplications | (() => ChildApplications) | undefined",
             "radioEvents": "?object | (() => object) | undefined",
             "radioRequests": "?object | (() => object) | undefined",
             "region": "?RegionDefinition | undefined",
@@ -614,6 +617,19 @@
           "callableMembers": [],
           "operationContracts": {}
         },
+        {
+          "name": "ApplicationStartOptions",
+          "kind": "type",
+          "signature": "ApplicationStartOptions",
+          "contracts": [
+            "type-shapes"
+          ],
+          "members": {
+            "region": "?RegionInstance<RegionOptions> | undefined"
+          },
+          "callableMembers": [],
+          "operationContracts": {}
+        },
         {
           "name": "Behavior",
           "kind": "value",
@@ -5342,7 +5358,7 @@
     },
     {
       "name": "@mnjs/utils",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/utils/src/index.ts",
       "conditions": {
@@ -5963,7 +5979,7 @@
     },
     {
       "name": "@mnjs/radio",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/radio/src/index.ts",
       "conditions": {
@@ -6424,7 +6440,7 @@
     },
     {
       "name": "@mnjs/data",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/data/src/index.ts",
       "conditions": {
@@ -6957,7 +6973,7 @@
     },
     {
       "name": "@mnjs/adapters/backbone",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/adapters/src/data/backbone.ts",
       "conditions": {
@@ -7032,7 +7048,7 @@
     },
     {
       "name": "@mnjs/adapters/dom/jquery",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/adapters/src/dom/jquery.ts",
       "conditions": {
@@ -7092,7 +7108,7 @@
     },
     {
       "name": "@mnjs/adapters/xstate",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/adapters/src/data/xstate.ts",
       "conditions": {
@@ -7179,7 +7195,7 @@
     },
     {
       "name": "@mnjs/adapters/dom/morphdom",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/adapters/src/dom/morphdom.ts",
       "conditions": {
@@ -7219,7 +7235,7 @@
     },
     {
       "name": "@mnjs/adapters/dom/lit-html",
-      "version": "5.0.0-beta.4",
+      "version": "5.0.0-beta.5",
       "kind": "runtime",
       "source": "packages/adapters/src/dom/lit-html.ts",
       "conditions": {
@@ -7444,6 +7460,13 @@
         "Region",
         "View"
       ]
+    },
+    {
+      "code": "MN0041",
+      "slug": "application-region-conflict",
+      "objects": [
+        "Application"
+      ]
     }
   ],
   "toolingEntrypoints": [
@@ -8030,7 +8053,7 @@
     "packages/utils/src/trigger-method.ts": "3a6460a5fdc6e0a319a6eea1e323f34f19fa0811ee1ea71fccaa45ade531d38f",
     "packages/utils/src/unique-id.ts": "22f5f12062eeef10c1336ee01e4b28b7d0cfe562c0f53f79e2a3219eb389f72b",
     "src/create-marionette.ts": "12baf1aadeeae54aefbb7e5777db9392f74650a407dcd506e97ebf18b73cfcc1",
-    "src/index.ts": "0fdbaa2bbb16566dd1032f786273e7b1acc8683390033b2c63b196e2dc04b449",
+    "src/index.ts": "41476602f9a5712f0742954fdc7d20a09bef62ba80711d25abe3d1bda8064656",
     "src/mixins/behaviors.ts": "720633138c31d36c3c9e9367c1cd9ef4a9b8514b2e5cfcb88e04bfdea7566991",
     "src/mixins/common.ts": "375340ed4f7c5db6c3bd9dc9d73c73b49e69347e3451c0db7dd646ae714f5156",
     "src/mixins/delegate-entity-events.ts": "778dc193ff0b32611e6a9112e133f961c2f522c6864ea847c70e7d676fb41c9c",
@@ -8041,7 +8064,7 @@
     "src/mixins/ui.ts": "5cb417e1456cd17b43357e480102be3fc1b436167c43b853af7d45ab79d35ffd",
     "src/mixins/view-events.ts": "108a31ba7d0f74916848c5b2f85b422afe15703a8e9fa2dbca0b17b6a5ff0fb2",
     "src/mixins/view.ts": "d0895d07d087d24d5cd8ce8d051a7acbbc9cee64fd2b5a6824b26973fc064e18",
-    "src/modules/application.ts": "3c6be0f0d93e171a5d258d19556c3955f34ff00726f70ec10a4262f84e9e82af",
+    "src/modules/application.ts": "a13c62d8e5985de4c05806c71265a051023ab845dc9b9c65fa120734494817e8",
     "src/modules/behavior.ts": "475fe0451e629559992bd0f5ec18ad16438309b018bf643b5917dfc47a1693b6",
     "src/modules/child-view-container.ts": "ab52685a0a4fd8861534b8e9784704791c3e72a15ee19547766293be4a030803",
     "src/modules/collection-view.ts": "40bbaefedea29de171597e905f8fdde7ee6f55877da9e441996c9b5bf56bfe58",
@@ -8062,39 +8085,41 @@
     "src/utils/subscribe-bindings.ts": "24633b6b39c2d0a8c833670e2ab1d584fb6bed2fae3ac5cfb5d42461cf233f4a"
   },
   "evidence": {
-    "config/diagnostics/catalog.json": "76cc4270e2ec939078cc3c8537d66e45bf0a58010fe25eeef81ab21f58886997",
+    "config/diagnostics/catalog.json": "45360deea6dfe7d531b256dbbebb443e9fa578fb0d43fc9becce7ab5126c76bf",
     "docs/choosing-integrations.md": "385bfb2c7d85a8e0db71fd795ed1fef488aa637aa5094e93210810ff91f31f12",
     "docs/common.md": "1d14004d1c49e98ca40be9fd28d35faaf372f2a12f13fae6afa3cac8a8bf14cc",
-    "docs/data.api.md": "5b714e990415d75982e78aaa62c0e86ad4b2fb0e75ea089fd994a080fdcee01a",
+    "docs/data.api.md": "f96a24fa8f08ed1437944d558e91878a16f941b7efd3dcc40c91b2de52d1f5a2",
     "docs/diagnostic-catalog.md": "1df844c7e8edbea59a8c07776d656d45f77266108babb770d7690183fe85d180",
     "docs/dom.api.md": "a697a637ae4c6cc92aa5d72850b404763f08e0417800feacc0b431ec073d3916",
     "docs/dom.interactions.md": "81bd678c7d498e08c08c84cfc3bbe1d27451ef46ed521e67fff4f72450bdbadb",
     "docs/events.class.md": "faed5ac4f6eca3ec447ae7cd44b6efd8f039e935b38a4c191076d485bd57a35f",
-    "docs/events.md": "227484aca95a4003903bd8df51f3c38c11144480ace919b63bacbf5bc2bb3d22",
-    "docs/marionette.application.md": "bbb8db3bc58f2b021d9dd77d748a3a005ee9b6a3410d3a897c171dc8b3fb1a85",
+    "docs/events.md": "8225ceda0d100b6bf466ab779cacc1001b7eec16b8dfd09d8c43d97924228e50",
+    "docs/marionette.application.md": "711283795f71f7bff273498e97a0e0c54a815f02f1ff9339a22fdf13d8bca048",
     "docs/marionette.behavior.md": "bf002b5ba380cf1bb1054b98f9813d89b4aef16ba6495d02b823ed178ab3f0c4",
     "docs/marionette.collectionview.md": "5af1ed04daaf0e976fdd0538b0931fd370fd09167079d0c21b01195f8628cefe",
     "docs/marionette.mnobject.md": "056bb3041902d66831a0031e2e9c97770f485f613450861ae55aba46ca592243",
-    "docs/marionette.region.md": "6716880b5ab5a6bf7b4b4a6dd7b66e7fdb7bd9c1c451578ad551d64f4be9e40d",
-    "docs/marionette.state.md": "fbee628142604499747a83f19055b05c0ba5831944760cf0910cc11cceef55f5",
+    "docs/marionette.region.md": "4b205c3699d771e6d6b288fd0914b15af80a7a76cfaaae9e63a92ac9ed0a6dee",
+    "docs/marionette.state.md": "2598f36fad1f5103f1f940312e311e1ed3c446d2e7725bdac690367511f73d97",
     "docs/marionette.view.md": "b7b5871b0b56474cc3bc2513c2e2c4fdabdafcd724bfbaa8076ea7eee40d5ab5",
-    "docs/optional-backbone.md": "8f8323ba79c77de961b81c1e6f9d3ed10efa5566629772054de201ea247ddaba",
+    "docs/optional-backbone.md": "f1d47cd797e109a9a57f56e1db187b50bafd16f1ff2775f03559f9f7e59bc86c",
     "docs/radio.md": "c0013e382554aa6cd4e46ab60908f5e6cce7117c134b3f4656c37a163f8a5f4e",
     "docs/runtime-isolation.md": "e18927a5aa30558805018c9c28dffceaf02d953394efce8eaa7d35f0711de7f4",
-    "docs/typescript.md": "47ec746e0dcc04cce56f6227f0645d4c777585a2ae797f00c4683b32585922f1",
+    "docs/typescript.md": "08361d38a3b3c29dcc45097fc44d74962cee91d9d97bea9f84006c1a9639e59b",
     "docs/utils.md": "5c2d0854895bb19f613926788cf81c5849cf18af1e43ac540e860b226fa80d2a",
-    "docs/view.lifecycle.md": "2cc29e59e056174bb2fcbd2888ee508ff6fb044b86e9fcacd1025c1f4e036133",
-    "docs/view.rendering.md": "6b397b0925b00c06ff644cd549b2273ba6235e1d6148ad6fa0514394f9c92df5",
-    "packages/adapters/readme.md": "67bca53b26a2facef67f4bc04931af31cbe9923167a9e62c98aa9789c40fd291",
-    "packages/data/readme.md": "45fe77f1744e39746be2c0f6ee872298f18fe9c12f7f7d94827c041b0e7f4b02",
-    "packages/utils/readme.md": "8ba1130cd1b6fd0aac3dd945d100bb2cebc8c87212890f1229a0863e2d9e4755",
+    "docs/view.lifecycle.md": "1e5f0e77d9bba799296ed40860a1d466e58cc086c36f72314cbe3c9daeedf8e3",
+    "docs/view.rendering.md": "106bd7c14f5897513a5072bed98d36e029b9be91650267f17ebcf90b03d8cb13",
+    "packages/adapters/readme.md": "d1be90d2631fcd4346b9e4648e7288e63ff28063fd7ffb860f32de25164d5d29",
+    "packages/data/readme.md": "041e330fad1a87c891844b774dd5309aae61cc7a36d76b3dcf9ec5dfcd7b8c95",
+    "packages/utils/readme.md": "2ea64109e9b65c9fb66d48c30fec86b6475aa4d8c809cc68c68a28925ed93021",
     "test/contracts/dom-adapters.js": "a3f71df6a2e52f8d4a52ebb2d3cbbc8e77e055f459daf7c071f4e5fd55ad8c3f",
+    "test/unit/application-child-declarations.spec.js": "3b98e033f99902a8bff5c533c03599375381da4b4a01b9014e825eb21cb80e2b",
     "test/unit/application-child-lifecycle.spec.js": "e69e6a140e341563b49333d09bd1c483151f9f4b2a494960a4dfc78bb81f8dcb",
     "test/unit/application-lifecycle.spec.js": "43da21063d3b03c1c16fd047735458a26a98abe003ef75e607bad0f01a473f37",
     "test/unit/application-ownership.spec.js": "f1e6a74f639bb6ceedd85957c696a45de28e1526ed41df0f34663a23b25bb68f",
     "test/unit/application-preparation.spec.js": "23e58351eec5983b4d412be099a7e9306f4b758a1f501874f46baca8be940b56",
-    "test/unit/application-prepared-view.spec.js": "440619dba9c73570974f1531bbe8b601fcb9a27ed64b499d6c10b9e8ca955dca",
-    "test/unit/application-root-view.spec.js": "2c1c642bb872836425b942580cc6600236cf3110186b427b1f7b2fd6263ff78d",
+    "test/unit/application-prepared-view.spec.js": "9d97d5e8f4783d3fb9ffff19afda25d46e6c6fd5f61a89929c42d559f2a2cee4",
+    "test/unit/application-root-view.spec.js": "e497b73aa9f1c67c228008dc744ba6675cfb7a72b3279367f95cf304d76b02da",
+    "test/unit/application-start-region.spec.js": "d29546de2a4f7a56153eaeee39386b9c3f07933fb11c6c4e4d3ad0fdf60bb703",
     "test/unit/backbone-adapter.spec.js": "016907f55d5e20d695f916dbd4189ac7e3e543a0f903df6a3922c207dade59df",
     "test/unit/behavior-lifecycle.spec.js": "8c70d05fa530d27eac901291a3487c9cacac1ef1d0c22a3adda917da5774d05a",
     "test/unit/behavior-ui-contract.spec.js": "65def27b40f17e3d931803faeff7c9dbb3c580e14f157fa5d2f8145fb95c1761",

package/dist/docs/config/api-contracts/semantics.json

@@ -1509,12 +1509,14 @@
         "Application"
       ],
       "result": "Operations resolve true at the requested target, false when superseded, and compatible calls share in-flight promises. Current readiness failure rejects the operation promise.",
-      "timing": "Before and completion notifications are synchronous and ignore returns. Only prepareStart/prepareStop/prepareDestroy are awaited with options and an abort context; start completion receives one resolved preparation result. Supersession aborts before replacement preparation; adopted stop retains its original context/options without abort.",
+      "timing": "Before and completion notifications are synchronous and ignore returns. Only prepareStart/prepareStop/prepareDestroy are awaited with options and an abort context; start completion receives one resolved preparation result. Supersession aborts before replacement preparation; adopted stop retains its original context/options without abort. Startup Region binding occurs before startup notifications, after any adopted stop readiness finishes.",
       "ownership": "Registration never starts children. Callers explicitly await prerequisites. Stop/destroy traverse all owned descendants, including stopped intermediate owners; descendants cannot start/restart during an ancestor stop or terminal phase.",
       "mutation": "Canceled readiness cannot append stale framework completion events or alter stable state.",
-      "repetition": "Compatible calls share promises. A stopped owner still drains owned descendants without repeating its own stop preparation or notifications. Restart deactivates children; reactivation is explicit.",
+      "repetition": "Compatible calls share promises. A stopped owner still drains owned descendants without repeating its own stop preparation or notifications. Restart deactivates children; reactivation is explicit. A different Region on start while running or starting is rejected with MN0041. Restart with a different host supersedes pending start/restart, deactivates first, then binds the latest host. A fresh start from stopped may bind a new host. Start-time region options accept only existing Region instances; constructor options retain Region definitions.",
       "destruction": "Destruction blocks owner and descendant start/restart; successful destruction destroys owned children. Readiness rejection preserves the documented retry and partial-child boundaries.",
-      "diagnostics": [],
+      "diagnostics": [
+        "MN0041"
+      ],
       "docs": [
         {
           "file": "docs/marionette.application.md",
@@ -1527,6 +1529,10 @@
         {
           "file": "docs/events.class.md",
           "heading": "Application Events"
+        },
+        {
+          "file": "docs/marionette.application.md",
+          "heading": "Starting an Application"
         }
       ],
       "tests": [
@@ -1573,6 +1579,14 @@
         {
           "file": "test/unit/application-preparation.spec.js",
           "title": "notifies before startup, awaits preparation, and forwards one result to completion"
+        },
+        {
+          "file": "test/unit/application-start-region.spec.js",
+          "title": "binds before startup notifications and forwards the complete options object"
+        },
+        {
+          "file": "test/unit/application-start-region.spec.js",
+          "title": "keeps a prepared root while rebinding a stopped displayed root"
         }
       ],
       "events": [
@@ -2340,15 +2354,16 @@
       "exports": [
         "Application"
       ],
-      "result": "Construction, addChildApp, setView and showView(view) return their public instance; showView() returns the prepared or current View, or undefined; removeChildApp returns a Promise of the removed child or undefined; queries return the declared state or optional owner member.",
-      "timing": "Construction, registration, root preparation/display and queries are synchronous; removeChildApp awaits child destruction before releasing ownership.",
-      "ownership": "Named children belong to the Application until removal. setView temporarily owns a prepared View; showView hands it to the Region and releases Application ownership. Without preparation, getView reads the Region currentView, including direct Region display.",
-      "mutation": "setView destroys only a previous prepared View, leaving the displayed View until Region show replaces it. getView reads preparation or current display without rendering. Child registration/removal coordinates with the owner lifecycle.",
-      "repetition": "Preparing the same pending View is a no-op; selecting the host currentView cancels preparation. Showing the current View does not render or attach it again. Child registrations and lookups follow documented ownership guards.",
-      "destruction": "Stop destroys a prepared View and empties the host. Destroy also tears down owned children and a constructed root Region; it preserves a borrowed Region. Direct destruction releases preparation; displayed Views follow Region cleanup and detachment.",
+      "result": "Construction, addChildApp, setView and showView(view) return their public instance; showView() returns the prepared or selected displayed View, or undefined; repeated showView() on the selected displayed root is a no-op; removeChildApp returns a Promise of the removed child or undefined; queries return the declared state or optional owner member.",
+      "timing": "Construction, registration, root preparation/display and queries are synchronous; removeChildApp awaits child destruction before releasing ownership. childApps resolves a map or function once and registers fresh no-argument children before initialize; declarations do not activate children. Parent restart retains registered instances without reconstructing or automatically reactivating them; start selected children explicitly.",
+      "ownership": "Named children belong to the Application until removal. setView temporarily owns a prepared View; showView hands it to the Region and records the Application's selected displayed root. A direct Region display is not adopted or claimable; an Application may reselect its own displayed root.",
+      "mutation": "setView destroys only a previous prepared View, leaving the selected displayed View until Region show replaces it. getView reads preparation or the Application's selected display without rendering. Child registration/removal coordinates with the owner lifecycle.",
+      "repetition": "Preparing the same pending View is a no-op; reselecting the Application's displayed root cancels preparation. Showing the current View does not render or attach it again. Child registrations and lookups follow documented ownership guards. Child declaration maps replace rather than merge inherited maps and are not reprocessed on restart.",
+      "destruction": "Stop destroys a prepared View and empties the host only when its selected displayed View is still current, or when a directly shown View occupies an Application-created Region. Destroy also tears down owned children and a constructed root Region; it preserves unrelated content in a borrowed Region. Direct destruction releases preparation; displayed View associations end on Region replacement, empty, or detachment.",
       "diagnostics": [
         "MN0003",
-        "MN0007"
+        "MN0007",
+        "MN0031"
       ],
       "docs": [
         {
@@ -2387,15 +2402,27 @@
         },
         {
           "file": "test/unit/application-root-view.spec.js",
-          "title": "shows and reads the current View of its Region"
+          "title": "shows and reads its selected View"
         },
         {
           "file": "test/unit/application-root-view.spec.js",
-          "title": "destroys an externally shown View but preserves its borrowed Region"
+          "title": "preserves an externally shown View and its borrowed Region"
         },
         {
           "file": "test/unit/application-prepared-view.spec.js",
           "title": "composes detached children through getView and updates one region after display"
+        },
+        {
+          "file": "test/unit/application-child-declarations.spec.js",
+          "title": "retains declared children through explicit activation and restart, then destroys them"
+        },
+        {
+          "file": "test/unit/application-child-declarations.spec.js",
+          "title": "replaces getter declarations through options without reading or assigning the getter"
+        },
+        {
+          "file": "test/unit/application-child-declarations.spec.js",
+          "title": "resolves a function declaration once with the parent as context before initialize"
         }
       ],
       "members": [

package/dist/docs/config/diagnostics/catalog.json

@@ -702,6 +702,22 @@
         "lint"
       ],
       "benchmarkCategory": "lifecycle"
+    },
+    {
+      "code": "MN0041",
+      "slug": "application-region-conflict",
+      "status": "active",
+      "category": "ownership",
+      "severity": "error",
+      "objects": [
+        "Application"
+      ],
+      "remediation": "Stop the Application before binding a different Region, or reuse the current Region while it is running or starting.",
+      "docsAnchor": "/errors/MN0041/",
+      "surfaces": [
+        "runtime"
+      ],
+      "benchmarkCategory": "ownership"
     }
   ]
 }

package/dist/docs/docs/agent-tools.md

@@ -92,13 +92,13 @@ and lockfile, including any npm alias. A v4 application may use
 marionette found” does not mean the application has no Marionette dependency.
 
 Download the exact target into a temporary directory without installing it in the
-application. This example inspects `5.0.0-beta.4`; set `migration_target_version` to
+application. This example inspects `5.0.0-beta.5`; set `migration_target_version` to
 the exact release selected for your migration, not `latest` or `next`. Downloading
 requires npm registry access; reading the extracted docs requires Node 24 or later.
 Run these commands in the same shell:
 
 ```sh
-migration_target_version="5.0.0-beta.4"
+migration_target_version="5.0.0-beta.5"
 migration_target_dir="$(mktemp -d)"
 npm pack "marionette@$migration_target_version" --ignore-scripts --pack-destination "$migration_target_dir"
 tar -xzf "$migration_target_dir/marionette-$migration_target_version.tgz" -C "$migration_target_dir"

package/dist/docs/docs/application-effects.md

@@ -22,11 +22,73 @@ changes. Starting from stopped creates a fresh scope.
 
 Canceling pending startup or rejecting its loader disposes the scope immediately.
 Terminal destruction
-also disposes effects. A readiness `signal` cancels only its pending phase; it is
+also disposes effects. A `prepareStart` signal covers only pending startup; it is
 not a signal for the entire subsequent run. The scope below owns that longer
 lifetime and passes its signal to the loader. Every awaited continuation checks
 cancellation before committing its result, including providers that ignore abort.
 
+## Recheck cancellation after awaited work
+
+A `prepareStart` signal belongs to its pending startup phase. Read
+`signal.aborted` after each awaited step before doing more work or committing its
+result. Capturing `const canceled = signal.aborted` before an await only records
+its earlier value. Checking `isRunning()` instead is also insufficient: a newer
+start may be running when an older request finally resolves.
+
+Stop preparation has different ownership: a replacement operation can adopt an
+in-flight `prepareStop` phase, retaining its original options and context without
+aborting its signal. The original caller's Promise resolving `false` does not mean
+that adopted work was canceled. See
+[preparation methods and notifications](./marionette.application.md#preparation-methods-and-notifications).
+
+This example loads and validates a value before committing it. Supply asynchronous
+`load({ signal })` and `validate(value, { signal })` functions and a synchronous
+`commit(value)` function. The checks protect the commit even when a provider ignores
+abort. They do not force that provider's Promise to settle or undo its own effects.
+
+<!-- executable-example: application-preparation-commit -->
+```javascript
+import { Application } from 'marionette';
+
+export function createPreparedFeature({ load, validate, commit }) {
+  const Feature = Application.extend({
+    async prepareStart(options, { signal }) {
+      const value = await load({ signal });
+      if (signal.aborted) { return; }
+      await validate(value, { signal });
+      if (signal.aborted) { return; }
+      commit(value);
+    }
+  });
+  return new Feature();
+}
+```
+
+If stop cancels startup while validation is pending, resolving validation later
+must not call `commit`. The second check is necessary even though the first check
+passed. Likewise, a newer successful start cannot authorize the old operation's
+commit. Use [latest-request ownership](./application-refresh.md#share-one-latest-request-controller)
+for independently replaceable refresh requests during an active run.
+The [installed preparation checks](https://github.com/marionettejs/marionette/blob/master/test/fixtures/docs-application-guides/preparation.mjs)
+exercise successful commit, canceled loading, and old validation completing after
+a newer successful start.
+
+## Distinguish delivery from resource cleanup
+
+Configured `stateEvents` can intentionally remain subscribed for the object's
+lifetime. A handler guarded by `isRunning()` suppresses its work while the feature
+is stopped, but does not unsubscribe or cancel a timer. It also suppresses work
+while stop permission is pending, because that is a lifecycle transition. Use the
+explicit scope below when effects must continue until stop succeeds and remain
+active if permission rejects. Disposing them in `onBeforeStop` would end them before
+the permission decision; disposal belongs in `onStop` for that policy.
+
+Successful `prepareStart` does not give its signal the lifetime of the subsequent
+active run. Register active resources with their own scope and dispose that scope
+on successful stop and terminal destruction. The executable example below and its
+[installed checks](https://github.com/marionettejs/marionette/blob/master/test/fixtures/docs-application-guides/effects.mjs)
+already cover rejected stop permission and successful timer cleanup.
+
 ## A complete feature
 
 Save this module as `status-feature.js`. Supply an element, an `@mnjs/data` Model,

package/dist/docs/docs/beta.md

@@ -1,6 +1,6 @@
 # Try Marionette v5 beta
 
-`5.0.0-beta.4` is prepared for application trials. Registry installation requires
+`5.0.0-beta.5` is prepared for application trials. Registry installation requires
 a published release; use certified tarballs before publication. Release promotion
 sets npm `latest` to the current prerelease until stable v5. A matching version
 string alone does not prove that a locally built artifact matches a release.
@@ -37,9 +37,10 @@ pins matching runtime dependencies; a candidate kit instead supplies exact local
 tarballs and a complete lockfile. Both include application agent instructions,
 typecheck, consumer lint, unit tests, build, and a browser-test command.
 
-The registry path requires beta.4 to be published first. Beta.3 remains the previous
-published candidate and awaits Application `onBefore*` hooks rather than this beta's
-`prepare*` methods. Move asynchronous preparation to the new methods before upgrading.
+The registry path requires beta.5 to be published first. Beta.4 remains the previous
+published candidate. Beta.5 adds ownership-aware root cleanup, existing Regions on
+start/restart, and static child declarations. When upgrading from beta.3 or earlier,
+move asynchronous `onBefore*` preparation to the corresponding `prepare*` methods.
 
 The starter has editable rows, asynchronous local selection, deliberate cancellation,
 and teardown. It has no backend, persistence, or URL router. Connect its `navigate`
@@ -83,7 +84,7 @@ permission, propagation, or trusted-publisher configuration.
 
 ## If the beta fails in your application
 
-Pin `5.0.0-beta.3` across all five packages and restore the matching application
+Pin `5.0.0-beta.4` across all five packages and restore the matching application
 code and lockfile. The old `marionette@5.0.0-alpha.2` is not an API-compatible
 rollback for this candidate. Existing v4 applications should retain their
 pre-migration revision and `backbone.marionette` lockfile until their beta trial
@@ -92,5 +93,5 @@ succeeds.
 Maintainers must not overwrite a published beta version. Withdraw its recommendation,
 deprecate a broken version with a specific reason, and publish a corrected beta.
 Move the selected npm tag (`latest` before the first stable v5) only to the verified
-beta.3 release. Preserve exact artifacts and failure evidence.
+beta.4 release. Preserve exact artifacts and failure evidence.
 See [release recovery](https://github.com/marionettejs/marionette/blob/master/docs/release-promotion.md#recovery-and-rollback).

package/dist/docs/docs/compact-reference.md

@@ -13,15 +13,15 @@ Use plain functions or classes when you do not need Marionette lifecycle, events
 | Region | show adopts a View; detach releases ownership without destroying it; empty/replacement destroy the current View. | [Lifecycle transition contract](./marionette.region.md) |
 | CollectionView | Managed children belong to the CollectionView; stable unchanged model sources preserve child identity; same-key replacement recreates a child. | [Managing Children](./marionette.collectionview.md) |
 | Behavior | Host owns top-level and nested Behaviors; direct Behavior destruction does not destroy its host. | [Behavior Lifecycle](./marionette.behavior.md) |
-| Application | Named children belong to the Application until removal. setView temporarily owns a prepared View; showView hands it to the Region and releases Application ownership. Without preparation, getView reads the Region currentView, including direct Region display. | [Application Lifecycle](./marionette.application.md) |
+| Application | Named children belong to the Application until removal. setView temporarily owns a prepared View; showView hands it to the Region and records the Application's selected displayed root. A direct Region display is not adopted or claimable; an Application may reselect its own displayed root. | [Application Lifecycle](./marionette.application.md) |
 
 ## Lifecycle and cancellation
 
 A synchronous callback/adapter exception escapes; no successful result or rollback is promised. Synchronous; callback or adapter exceptions abort the operation without rollback or attempt-all cleanup. Accepted idempotence guards remain; Application asynchronous cancellation is a distinct contract. [Synchronous failures](./view.lifecycle.md).
 
-Operations resolve true at the requested target, false when superseded, and compatible calls share in-flight promises. Current readiness failure rejects the operation promise. Before and completion notifications are synchronous and ignore returns. Only prepareStart/prepareStop/prepareDestroy are awaited with options and an abort context; start completion receives one resolved preparation result. Supersession aborts before replacement preparation; adopted stop retains its original context/options without abort. Destruction blocks owner and descendant start/restart; successful destruction destroys owned children. Readiness rejection preserves the documented retry and partial-child boundaries. [Application Lifecycle](./marionette.application.md).
+Operations resolve true at the requested target, false when superseded, and compatible calls share in-flight promises. Current readiness failure rejects the operation promise. Before and completion notifications are synchronous and ignore returns. Only prepareStart/prepareStop/prepareDestroy are awaited with options and an abort context; start completion receives one resolved preparation result. Supersession aborts before replacement preparation; adopted stop retains its original context/options without abort. Startup Region binding occurs before startup notifications, after any adopted stop readiness finishes. Destruction blocks owner and descendant start/restart; successful destruction destroys owned children. Readiness rejection preserves the documented retry and partial-child boundaries. [Application Lifecycle](./marionette.application.md).
 
-Construction, addChildApp, setView and showView(view) return their public instance; showView() returns the prepared or current View, or undefined; removeChildApp returns a Promise of the removed child or undefined; queries return the declared state or optional owner member. Construction, registration, root preparation/display and queries are synchronous; removeChildApp awaits child destruction before releasing ownership. Stop destroys a prepared View and empties the host. Destroy also tears down owned children and a constructed root Region; it preserves a borrowed Region. Direct destruction releases preparation; displayed Views follow Region cleanup and detachment. [Application Lifecycle](./marionette.application.md).
+Construction, addChildApp, setView and showView(view) return their public instance; showView() returns the prepared or selected displayed View, or undefined; repeated showView() on the selected displayed root is a no-op; removeChildApp returns a Promise of the removed child or undefined; queries return the declared state or optional owner member. Construction, registration, root preparation/display and queries are synchronous; removeChildApp awaits child destruction before releasing ownership. childApps resolves a map or function once and registers fresh no-argument children before initialize; declarations do not activate children. Parent restart retains registered instances without reconstructing or automatically reactivating them; start selected children explicitly. Stop destroys a prepared View and empties the host only when its selected displayed View is still current, or when a directly shown View occupies an Application-created Region. Destroy also tears down owned children and a constructed root Region; it preserves unrelated content in a borrowed Region. Direct destruction releases preparation; displayed View associations end on Region replacement, empty, or detachment. [Application Lifecycle](./marionette.application.md).
 
 Application readiness cancellation prevents stale framework completion. Application code must also respect the readiness signal before committing its own asynchronous side effects. Completion hooks are synchronous notifications. Use the [routing recipe](./routing.md) for cooperative cancellation and late-result checks.
 
@@ -112,6 +112,7 @@ Match a framework invariant by its stable diagnostic code, not message prose. Th
 | `MN0037` | adapter-observation-unsupported |
 | `MN0039` | collection-data-contract-invalid |
 | `MN0040` | private-framework-member-access |
+| `MN0041` | application-region-conflict |
 
 Use public return values, DOM state, child identity, events, and externally counted subscriptions to prove behavior. Test focus and editable state in a real browser; test cancellation with held readiness and late results. A generated contract record proves consistency, not behavior or agent effectiveness.
 

package/dist/docs/docs/data.api.md

@@ -216,7 +216,7 @@ Install `@mnjs/data` with `marionette` when an application wants a small
 first-party observable Model and ordered Collection without Backbone:
 
 ```sh
-npm install marionette@5.0.0-beta.4 @mnjs/data@5.0.0-beta.4
+npm install marionette@5.0.0-beta.5 @mnjs/data@5.0.0-beta.5
 ```
 
 ```javascript
@@ -226,13 +226,16 @@ import { Collection, DataApi, Model, StateApi } from '@mnjs/data';
 setDataApi(DataApi);
 setStateApi(StateApi);
 
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, character => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'
+  }[character]));
+}
+
 const RowView = View.extend({
   tagName: 'li',
-  template: () => '',
-  modelEvents: { change: 'render' },
-  onRender() {
-    this.el.textContent = this.model.get('label');
-  }
+  template: ({ label }) => escapeHtml(label),
+  modelEvents: { change: 'render' }
 });
 const state = new Model({ selectedId: null });
 const collection = new Collection([{ id: 1, label: 'one' }]);

package/dist/docs/docs/events.md

@@ -10,6 +10,7 @@ events are separate from [DOM events](./dom.interactions.md#canonical-view-inter
 * [Triggering and Listening to Events](#triggering-and-listening-to-events)
   * [Events API](#events-api)
   * [`triggerMethod`](#triggermethod)
+    * [Resources created in lifecycle methods](#resources-created-in-lifecycle-methods)
   * [Listening to Events](#listening-to-events)
     * [`onEvent` Binding](#onevent-binding)
   * [Backbone interop](#backbone-interop)
@@ -130,6 +131,12 @@ myView.triggerMethod('something:happened', 'foo');
 
 **The `triggerMethod` method is available to [all Marionette classes](./common.md#triggermethod).**
 
+#### Resources created in lifecycle methods
+
+A lifecycle method runs before its matching event is emitted. A listener registered inside `onRender` for `render` can therefore run during that same render. Using `once` only limits the number of calls; it does not wait for the next lifecycle operation.
+
+If `onRender` creates a resource that must survive until the next render, release the previous resource in `onBeforeRender` (or on `before:render`), and release the current resource in `onBeforeDestroy` (or on `before:destroy`). Pick cleanup boundaries from the resource's actual lifetime rather than subscribing to the event that is still creating it. Keep cleanup idempotent when two termination paths can apply.
+
 ### Listening to Events
 
 Use `on` to register a callback directly on an emitter: