marionette 5.0.0-beta.3 → 5.0.0-beta.4

package/changelog.md

@@ -1,4 +1,18 @@
-### Unreleased
+### v5.0.0-beta.4
+
+> Events announce. Preparation waits. Apparently those needed separate job descriptions.
+
+* Separate Application preparation from lifecycle notifications. Await
+  `prepareStart`, `prepareStop`, and `prepareDestroy`; `onBefore*` hooks and
+  `before:*` events are synchronous notifications. Pass `prepareStart`'s resolved
+  value unchanged to `onStart` and `start` as the third argument. Migrate async
+  `onBefore*` work to the corresponding preparation method.
+* Preserve inferred startup result types for optional preparation methods, including
+  `undefined` when the method is absent.
+* Include referenced consumer resources in documentation exports and keep maintainer
+  material out of the packaged consumer documentation.
+* Clarify packaged and copied agent-skill helper paths, with executable lookup
+  examples checked against the installed documentation.
 
 ### v5.0.0-beta.3
 

package/dist/agent-skill/SKILL.md

@@ -11,11 +11,20 @@ choices. This skill does not authorize dependency upgrades.
 ## Locate matching docs
 
 Resolve the package from the application workspace, not the copied skill directory
-or a neighboring monorepo package. The read-only helper requires Node 24 or later:
+or a neighboring monorepo package. The read-only helper requires Node 24 or later.
+Its path is `scripts/docs.mjs` relative to the directory containing this `SKILL.md`:
+
+- In the npm package, that directory is `<package-root>/dist/agent-skill/`.
+- After copying the skill, it is the copied directory, such as
+  `/path/to/application/.agents/skills/marionette/`.
+
+Replace `/path/to/skill-directory` with that directory's absolute path and
+`/path/to/application` with the application's absolute path. These commands work
+from any working directory:
 
 ```sh
-node /path/to/marionette/scripts/docs.mjs --project /path/to/application --list
-node /path/to/marionette/scripts/docs.mjs --project /path/to/application --page docs/agents.md
+node "/path/to/skill-directory/scripts/docs.mjs" --project "/path/to/application" --list
+node "/path/to/skill-directory/scripts/docs.mjs" --project "/path/to/application" --page docs/agents.md
 ```
 
 These are lookup options, not a required sequence. `--list` returns provenance and

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

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "authority": "authored TypeScript and explicit public behavioral evidence",
-  "semanticsSha256": "c007c7b263af096f58e58b22347ff1b67c7a4f66abb63b4a2be5d2b73ecd9e30",
+  "semanticsSha256": "0929a305cce177355389fafdc1c5b46d8332046647ce7c970b27b49be866c616",
   "entrypoints": [
     {
       "name": "marionette",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "src/index.ts",
       "conditions": {
@@ -39,7 +39,7 @@
           "members": {
             "apply": "(receiver: object, args: IArguments | [options?: ApplicationOptions | undefined]) => void",
             "call": "(receiver: object, options?: ApplicationOptions | undefined) => void",
-            "extend": "<Added extends object = {}, AddedStatics extends object = {}>(this: Added extends { constructor: (...args: never[]) => unknown; } ? object : (this: object, ...args: never[]) => unknown, prototypeProperties?: (Added & ThisType<Merge<ApplicationInstance<Merge<DefaultOptions<Added>, OptionsFor<ArgumentsFor<Added, [options?: ApplicationOptions | undefined]>>>, SuppliedState<Added, Added extends { createState: (...args: never[]) => infer State; } ? State : object>>, \"options\" extends keyof Added ? Omit<Added, keyof Added & \"options\"> : Added>>) | undefined, staticProperties?: (AddedStatics & ThisType<ApplicationConstructor<Added, ArgumentsFor<Added, [options?: ApplicationOptions | undefined]>, SuppliedState<Added, Added extends { createState: (...args: never[]) => infer State; } ? State : object>, AddedStatics>>) | undefined) => ApplicationConstructor<Added, ArgumentsFor<Added, [options?: ApplicationOptions | undefined]>, SuppliedState<Added, Added extends { createState: (...args: never[]) => infer State; } ? State : object>, AddedStatics>",
+            "extend": "<Added extends object = {}, AddedStatics extends object = {}>(this: Added extends { constructor: (...args: never[]) => unknown; } ? object : (this: object, ...args: never[]) => unknown, prototypeProperties?: (Added & ThisType<Merge<ApplicationInstance<Merge<DefaultOptions<Added>, OptionsFor<ArgumentsFor<Added, [options?: ApplicationOptions | undefined]>>>, SuppliedState<Added, Added extends { createState: (...args: never[]) => infer State; } ? State : object>, StartResultFor<Added>>, \"options\" extends keyof Added ? Omit<Added, keyof Added & \"options\"> : Added>>) | undefined, staticProperties?: (AddedStatics & ThisType<ApplicationConstructor<Added, ArgumentsFor<Added, [options?: ApplicationOptions | undefined]>, SuppliedState<Added, Added extends { createState: (...args: never[]) => infer State; } ? State : object>, AddedStatics>>) | undefined) => ApplicationConstructor<Added, ArgumentsFor<Added, [options?: ApplicationOptions | undefined]>, SuppliedState<Added, Added extends { createState: (...args: never[]) => infer State; } ? State : object>, AddedStatics>",
             "setStateApi": "<Receiver extends StateApiClass, Mixin extends object>(this: Receiver, mixin?: string | number | bigint | boolean | symbol | (Mixin & Partial<StateApi<never>>) | null | undefined) => Receiver"
           },
           "callableMembers": [
@@ -49,7 +49,7 @@
             "setStateApi"
           ],
           "construct": [
-            "<Provided extends [options?: ApplicationOptions | undefined] = [options?: ApplicationOptions | undefined]>(...args: Provided): ApplicationInstance<object & OptionsFor<Provided>, SuppliedState<Provided[0], object>>"
+            "<Provided extends [options?: ApplicationOptions | undefined] = [options?: ApplicationOptions | undefined]>(...args: Provided): ApplicationInstance<object & OptionsFor<Provided>, SuppliedState<Provided[0], object>, unknown>"
           ],
           "instance": {
             "addChildApp": "<Child extends ApplicationInstance<object, unknown>>(name: string, application: Child) => Child",
@@ -61,8 +61,8 @@
             "createState": "(options?: (object & ApplicationOptions) | undefined) => unknown",
             "destroy": "(options?: unknown) => Promise<boolean>",
             "getChannel": "() => Channel | undefined",
-            "getChildApp": "(name: string) => ApplicationInstance<object, unknown> | undefined",
-            "getChildApps": "() => Record<string, ApplicationInstance<object, unknown>>",
+            "getChildApp": "(name: string) => ApplicationInstance<object, unknown, unknown> | undefined",
+            "getChildApps": "() => Record<string, ApplicationInstance<object, unknown, unknown>>",
             "getName": "() => string | undefined",
             "getOption": "{ (optionName?: null | undefined): undefined; <Receiver extends object, Name extends PropertyKey | null | undefined>(this: Receiver, optionName: Name): GetOptionResult<Receiver, Name>; (this: object, optionName: PropertyKey | null | undefined): unknown; }",
             "getRegion": "() => RegionInstance<RegionOptions> | undefined",
@@ -78,21 +78,24 @@
             "normalizeMethods": "{ (this: unknown, hash?: false | \"\" | 0 | 0n | null | undefined): undefined; (this: unknown, hash: object): EventMap; (this: unknown, hash?: OptionalBindings): EventMap | undefined; }",
             "off": "{ <Receiver>(this: Receiver, name?: string | null | undefined, callback?: EventCallback | null | undefined, context?: unknown): Receiver; <Receiver>(this: Receiver, events: EventMap, context?: unknown, explicitContext?: unknown): Receiver; }",
             "on": "{ <Receiver>(this: Receiver, name: string, callback?: EventCallback | undefined, context?: unknown): Receiver; <Receiver>(this: Receiver, events: EventMap, context?: unknown, explicitContext?: unknown): Receiver; }",
-            "onBeforeDestroy": "?((application: ApplicationInstance<object & ApplicationOptions, object>, options: unknown, context: LifecycleContext) => unknown) | undefined",
-            "onBeforeStart": "?((application: ApplicationInstance<object & ApplicationOptions, object>, options: unknown, context: LifecycleContext) => unknown) | undefined",
-            "onBeforeStop": "?((application: ApplicationInstance<object & ApplicationOptions, object>, options: unknown, context: LifecycleContext) => unknown) | undefined",
+            "onBeforeDestroy": "?((application: ApplicationInstance<object & ApplicationOptions, object, unknown>, options: unknown) => unknown) | undefined",
+            "onBeforeStart": "?((application: ApplicationInstance<object & ApplicationOptions, object, unknown>, options: unknown) => unknown) | undefined",
+            "onBeforeStop": "?((application: ApplicationInstance<object & ApplicationOptions, object, unknown>, options: unknown) => unknown) | undefined",
             "once": "{ <Receiver>(this: Receiver, name: string, callback?: EventCallback | undefined, context?: unknown): Receiver; <Receiver>(this: Receiver, events: EventMap, context?: unknown, explicitContext?: unknown): Receiver; }",
-            "onDestroy": "?((application: ApplicationInstance<object & ApplicationOptions, object>, options: unknown) => unknown) | undefined",
-            "onStart": "?((application: ApplicationInstance<object & ApplicationOptions, object>, options: unknown) => unknown) | undefined",
-            "onStop": "?((application: ApplicationInstance<object & ApplicationOptions, object>, options: unknown) => unknown) | undefined",
+            "onDestroy": "?((application: ApplicationInstance<object & ApplicationOptions, object, unknown>, options: unknown) => unknown) | undefined",
+            "onStart": "?((application: ApplicationInstance<object & ApplicationOptions, object, unknown>, options: unknown, result: unknown) => unknown) | undefined",
+            "onStop": "?((application: ApplicationInstance<object & ApplicationOptions, object, unknown>, options: unknown) => unknown) | undefined",
             "options": "object & ApplicationOptions",
             "preinitialize": "(options?: (object & ApplicationOptions) | undefined) => void",
+            "prepareDestroy": "?((options: unknown, context: LifecycleContext) => unknown) | undefined",
+            "prepareStart": "?((options: unknown, context: LifecycleContext) => unknown) | undefined",
+            "prepareStop": "?((options: unknown, context: LifecycleContext) => unknown) | undefined",
             "Radio": "RadioApi",
             "radioEvents": "?object | (() => object) | undefined",
             "radioRequests": "?object | (() => object) | undefined",
             "region": "?RegionDefinition | undefined",
             "regionClass": "RegionClass",
-            "removeChildApp": "(name: string, options?: unknown) => Promise<ApplicationInstance<object, unknown> | undefined>",
+            "removeChildApp": "(name: string, options?: unknown) => Promise<ApplicationInstance<object, unknown, unknown> | undefined>",
             "restart": "(options?: unknown) => 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; }",
@@ -139,6 +142,9 @@
             "onStart",
             "onStop",
             "preinitialize",
+            "prepareDestroy",
+            "prepareStart",
+            "prepareStop",
             "removeChildApp",
             "restart",
             "setView",
@@ -257,6 +263,15 @@
               "preinitialize": [
                 "application-composition"
               ],
+              "prepareDestroy": [
+                "application-lifecycle"
+              ],
+              "prepareStart": [
+                "application-lifecycle"
+              ],
+              "prepareStop": [
+                "application-lifecycle"
+              ],
               "removeChildApp": [
                 "application-composition"
               ],
@@ -309,7 +324,7 @@
             "call"
           ],
           "construct": [
-            "<Provided extends Args = Args>(...args: Provided): Constructed<Props, Merge<ApplicationInstance<Merge<DefaultOptions<Props>, OptionsFor<Provided>>, SuppliedState<Provided[0], State>>, \"options\" extends keyof Props ? Omit<Props, keyof Props & \"options\"> : Props>>"
+            "<Provided extends Args = Args>(...args: Provided): Constructed<Props, Merge<ApplicationInstance<Merge<DefaultOptions<Props>, OptionsFor<Provided>>, SuppliedState<Provided[0], State>, StartResultFor<Props>>, \"options\" extends keyof Props ? Omit<Props, keyof Props & \"options\"> : Props>>"
           ],
           "instance": {},
           "callableInstanceMembers": [],
@@ -330,7 +345,7 @@
         {
           "name": "ApplicationInstance",
           "kind": "type",
-          "signature": "ApplicationInstance<Options, State>",
+          "signature": "ApplicationInstance<Options, State, StartResult>",
           "contracts": [
             "type-shapes"
           ],
@@ -344,8 +359,8 @@
             "createState": "(options?: Options | undefined) => unknown",
             "destroy": "(options?: unknown) => Promise<boolean>",
             "getChannel": "() => Channel | undefined",
-            "getChildApp": "(name: string) => ApplicationInstance<object, unknown> | undefined",
-            "getChildApps": "() => Record<string, ApplicationInstance<object, unknown>>",
+            "getChildApp": "(name: string) => ApplicationInstance<object, unknown, unknown> | undefined",
+            "getChildApps": "() => Record<string, ApplicationInstance<object, unknown, unknown>>",
             "getName": "() => string | undefined",
             "getOption": "{ (optionName?: null | undefined): undefined; <Receiver extends object, Name extends PropertyKey | null | undefined>(this: Receiver, optionName: Name): GetOptionResult<Receiver, Name>; (this: object, optionName: PropertyKey | null | undefined): unknown; }",
             "getRegion": "() => RegionInstance<RegionOptions> | undefined",
@@ -361,21 +376,24 @@
             "normalizeMethods": "{ (this: unknown, hash?: false | \"\" | 0 | 0n | null | undefined): undefined; (this: unknown, hash: object): EventMap; (this: unknown, hash?: OptionalBindings): EventMap | undefined; }",
             "off": "{ <Receiver>(this: Receiver, name?: string | null | undefined, callback?: EventCallback | null | undefined, context?: unknown): Receiver; <Receiver>(this: Receiver, events: EventMap, context?: unknown, explicitContext?: unknown): Receiver; }",
             "on": "{ <Receiver>(this: Receiver, name: string, callback?: EventCallback | undefined, context?: unknown): Receiver; <Receiver>(this: Receiver, events: EventMap, context?: unknown, explicitContext?: unknown): Receiver; }",
-            "onBeforeDestroy": "?((application: ApplicationInstance<Options, State>, options: unknown, context: LifecycleContext) => unknown) | undefined",
-            "onBeforeStart": "?((application: ApplicationInstance<Options, State>, options: unknown, context: LifecycleContext) => unknown) | undefined",
-            "onBeforeStop": "?((application: ApplicationInstance<Options, State>, options: unknown, context: LifecycleContext) => unknown) | undefined",
+            "onBeforeDestroy": "?((application: ApplicationInstance<Options, State, StartResult>, options: unknown) => unknown) | undefined",
+            "onBeforeStart": "?((application: ApplicationInstance<Options, State, StartResult>, options: unknown) => unknown) | undefined",
+            "onBeforeStop": "?((application: ApplicationInstance<Options, State, StartResult>, options: unknown) => unknown) | undefined",
             "once": "{ <Receiver>(this: Receiver, name: string, callback?: EventCallback | undefined, context?: unknown): Receiver; <Receiver>(this: Receiver, events: EventMap, context?: unknown, explicitContext?: unknown): Receiver; }",
-            "onDestroy": "?((application: ApplicationInstance<Options, State>, options: unknown) => unknown) | undefined",
-            "onStart": "?((application: ApplicationInstance<Options, State>, options: unknown) => unknown) | undefined",
-            "onStop": "?((application: ApplicationInstance<Options, State>, options: unknown) => unknown) | undefined",
+            "onDestroy": "?((application: ApplicationInstance<Options, State, StartResult>, options: unknown) => unknown) | undefined",
+            "onStart": "?((application: ApplicationInstance<Options, State, StartResult>, options: unknown, result: StartResult) => unknown) | undefined",
+            "onStop": "?((application: ApplicationInstance<Options, State, StartResult>, options: unknown) => unknown) | undefined",
             "options": "Options",
             "preinitialize": "(options?: Options | undefined) => void",
+            "prepareDestroy": "?((options: unknown, context: LifecycleContext) => unknown) | undefined",
+            "prepareStart": "?((options: unknown, context: LifecycleContext) => StartResult | PromiseLike<StartResult>) | undefined",
+            "prepareStop": "?((options: unknown, context: LifecycleContext) => unknown) | undefined",
             "Radio": "RadioApi",
             "radioEvents": "?object | (() => object) | undefined",
             "radioRequests": "?object | (() => object) | undefined",
             "region": "?RegionDefinition | undefined",
             "regionClass": "RegionClass",
-            "removeChildApp": "(name: string, options?: unknown) => Promise<ApplicationInstance<object, unknown> | undefined>",
+            "removeChildApp": "(name: string, options?: unknown) => Promise<ApplicationInstance<object, unknown, unknown> | undefined>",
             "restart": "(options?: unknown) => 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; }",
@@ -422,6 +440,9 @@
             "onStart",
             "onStop",
             "preinitialize",
+            "prepareDestroy",
+            "prepareStart",
+            "prepareStop",
             "removeChildApp",
             "restart",
             "setView",
@@ -529,6 +550,15 @@
               "preinitialize": [
                 "type-shapes"
               ],
+              "prepareDestroy": [
+                "type-shapes"
+              ],
+              "prepareStart": [
+                "type-shapes"
+              ],
+              "prepareStop": [
+                "type-shapes"
+              ],
               "removeChildApp": [
                 "type-shapes"
               ],
@@ -5312,7 +5342,7 @@
     },
     {
       "name": "@mnjs/utils",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/utils/src/index.ts",
       "conditions": {
@@ -5933,7 +5963,7 @@
     },
     {
       "name": "@mnjs/radio",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/radio/src/index.ts",
       "conditions": {
@@ -6394,7 +6424,7 @@
     },
     {
       "name": "@mnjs/data",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/data/src/index.ts",
       "conditions": {
@@ -6927,7 +6957,7 @@
     },
     {
       "name": "@mnjs/adapters/backbone",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/adapters/src/data/backbone.ts",
       "conditions": {
@@ -7002,7 +7032,7 @@
     },
     {
       "name": "@mnjs/adapters/dom/jquery",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/adapters/src/dom/jquery.ts",
       "conditions": {
@@ -7062,7 +7092,7 @@
     },
     {
       "name": "@mnjs/adapters/xstate",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/adapters/src/data/xstate.ts",
       "conditions": {
@@ -7149,7 +7179,7 @@
     },
     {
       "name": "@mnjs/adapters/dom/morphdom",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/adapters/src/dom/morphdom.ts",
       "conditions": {
@@ -7189,7 +7219,7 @@
     },
     {
       "name": "@mnjs/adapters/dom/lit-html",
-      "version": "5.0.0-beta.3",
+      "version": "5.0.0-beta.4",
       "kind": "runtime",
       "source": "packages/adapters/src/dom/lit-html.ts",
       "conditions": {
@@ -7806,8 +7836,7 @@
       "kind": "literal",
       "arguments": [
         "application",
-        "options",
-        "context"
+        "options"
       ]
     },
     {
@@ -7816,7 +7845,8 @@
       "kind": "literal",
       "arguments": [
         "application",
-        "options"
+        "options",
+        "result"
       ]
     },
     {
@@ -7825,8 +7855,7 @@
       "kind": "literal",
       "arguments": [
         "application",
-        "options",
-        "context"
+        "options"
       ]
     },
     {
@@ -7844,8 +7873,7 @@
       "kind": "literal",
       "arguments": [
         "this",
-        "options",
-        "context"
+        "options"
       ]
     },
     {
@@ -8013,7 +8041,7 @@
     "src/mixins/ui.ts": "5cb417e1456cd17b43357e480102be3fc1b436167c43b853af7d45ab79d35ffd",
     "src/mixins/view-events.ts": "108a31ba7d0f74916848c5b2f85b422afe15703a8e9fa2dbca0b17b6a5ff0fb2",
     "src/mixins/view.ts": "d0895d07d087d24d5cd8ce8d051a7acbbc9cee64fd2b5a6824b26973fc064e18",
-    "src/modules/application.ts": "11a9541a102d67f1d76ca83ec4bd65e8d68bfc7790e818aaeded14965dae42ec",
+    "src/modules/application.ts": "3c6be0f0d93e171a5d258d19556c3955f34ff00726f70ec10a4262f84e9e82af",
     "src/modules/behavior.ts": "475fe0451e629559992bd0f5ec18ad16438309b018bf643b5917dfc47a1693b6",
     "src/modules/child-view-container.ts": "ab52685a0a4fd8861534b8e9784704791c3e72a15ee19547766293be4a030803",
     "src/modules/collection-view.ts": "40bbaefedea29de171597e905f8fdde7ee6f55877da9e441996c9b5bf56bfe58",
@@ -8037,33 +8065,34 @@
     "config/diagnostics/catalog.json": "76cc4270e2ec939078cc3c8537d66e45bf0a58010fe25eeef81ab21f58886997",
     "docs/choosing-integrations.md": "385bfb2c7d85a8e0db71fd795ed1fef488aa637aa5094e93210810ff91f31f12",
     "docs/common.md": "1d14004d1c49e98ca40be9fd28d35faaf372f2a12f13fae6afa3cac8a8bf14cc",
-    "docs/data.api.md": "c4e946abf9806eadb86996f296de3b06e5265e0e724186ff33e172e5f43d8a23",
+    "docs/data.api.md": "5b714e990415d75982e78aaa62c0e86ad4b2fb0e75ea089fd994a080fdcee01a",
     "docs/diagnostic-catalog.md": "1df844c7e8edbea59a8c07776d656d45f77266108babb770d7690183fe85d180",
     "docs/dom.api.md": "a697a637ae4c6cc92aa5d72850b404763f08e0417800feacc0b431ec073d3916",
     "docs/dom.interactions.md": "81bd678c7d498e08c08c84cfc3bbe1d27451ef46ed521e67fff4f72450bdbadb",
-    "docs/events.class.md": "7370bdc890168105ab61fd6140aae9f43ec473a0872fd7cdf1812d2cf9fd9e00",
+    "docs/events.class.md": "faed5ac4f6eca3ec447ae7cd44b6efd8f039e935b38a4c191076d485bd57a35f",
     "docs/events.md": "227484aca95a4003903bd8df51f3c38c11144480ace919b63bacbf5bc2bb3d22",
-    "docs/marionette.application.md": "9bf34ebf6130126135129ac04b03d37ee24ba7868d5596a15ffafdcbdc9af5a3",
+    "docs/marionette.application.md": "bbb8db3bc58f2b021d9dd77d748a3a005ee9b6a3410d3a897c171dc8b3fb1a85",
     "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.view.md": "b7b5871b0b56474cc3bc2513c2e2c4fdabdafcd724bfbaa8076ea7eee40d5ab5",
-    "docs/optional-backbone.md": "f630fdcf2d6659cd4b0a7bf76c5e18ce9ae92312e35e98e312fb8afea4c1d664",
+    "docs/optional-backbone.md": "8f8323ba79c77de961b81c1e6f9d3ed10efa5566629772054de201ea247ddaba",
     "docs/radio.md": "c0013e382554aa6cd4e46ab60908f5e6cce7117c134b3f4656c37a163f8a5f4e",
     "docs/runtime-isolation.md": "e18927a5aa30558805018c9c28dffceaf02d953394efce8eaa7d35f0711de7f4",
     "docs/typescript.md": "47ec746e0dcc04cce56f6227f0645d4c777585a2ae797f00c4683b32585922f1",
     "docs/utils.md": "5c2d0854895bb19f613926788cf81c5849cf18af1e43ac540e860b226fa80d2a",
     "docs/view.lifecycle.md": "2cc29e59e056174bb2fcbd2888ee508ff6fb044b86e9fcacd1025c1f4e036133",
     "docs/view.rendering.md": "6b397b0925b00c06ff644cd549b2273ba6235e1d6148ad6fa0514394f9c92df5",
-    "packages/adapters/readme.md": "3199ad1d13ca2ea6253c6f95af1806d7b2b28680074b5488da861b2af1aaaba5",
-    "packages/data/readme.md": "ca98cee5fcb519278b47e9a12e3e8838f5e9c9c5913646c14398fc7111d6f8d6",
-    "packages/utils/readme.md": "8fe46e7f62e691e208ef87bba47ec0209302cfed15faa0d87a221f66cf666348",
+    "packages/adapters/readme.md": "67bca53b26a2facef67f4bc04931af31cbe9923167a9e62c98aa9789c40fd291",
+    "packages/data/readme.md": "45fe77f1744e39746be2c0f6ee872298f18fe9c12f7f7d94827c041b0e7f4b02",
+    "packages/utils/readme.md": "8ba1130cd1b6fd0aac3dd945d100bb2cebc8c87212890f1229a0863e2d9e4755",
     "test/contracts/dom-adapters.js": "a3f71df6a2e52f8d4a52ebb2d3cbbc8e77e055f459daf7c071f4e5fd55ad8c3f",
-    "test/unit/application-child-lifecycle.spec.js": "fae6cd469119901a1a39e1ee9f8aa5aae55db39d50df7a3cb145e640fba8d400",
-    "test/unit/application-lifecycle.spec.js": "52adc58534d8cb079dacb9b8b5f608bd62783c14ad5b98bb8cd85dcdd757c331",
-    "test/unit/application-ownership.spec.js": "6710968792d0c52877110abc63b4622b18efc3b030d5f5f1060e4de046326095",
+    "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/backbone-adapter.spec.js": "016907f55d5e20d695f916dbd4189ac7e3e543a0f903df6a3922c207dade59df",
@@ -8090,7 +8119,7 @@
     "test/unit/events-parity.spec.js": "a0ec7cd3dac3636803ec6ecc6fb7161df2a74fa7d5e6d532477e12539a9bd71c",
     "test/unit/events-single-dispatch.spec.js": "9405ceb5a59c4ebddf3aeb4a902588dcf81a6bc35aca40bde0e8aa41760fb6ce",
     "test/unit/jquery-dom-api.spec.js": "4b0187d3ca5dac647394dd906fe6c6ca11764688c12ef864bc4eae867a629ded",
-    "test/unit/model-based/application.spec.js": "606f73e131faa4991ac2dc5370abc80b0f61467623705b0d929587e654cc7e35",
+    "test/unit/model-based/application.spec.js": "e40a27ede3317869f8e3a1e10563be78f1bfe768365d62bcd1fedd38322a84ed",
     "test/unit/modules-error.spec.js": "3ca32416b3329999cb3fcdd3fbc66751d722e7a2c0082195b702b64dce6284c3",
     "test/unit/object.spec.js": "ca82986738229a1af224aa3bd2b0ab88d70ca92dc556806796e5b056b19ebb3e",
     "test/unit/provider-acceptance.spec.js": "9eb8795a222745b41ba2d76ae770dfa702e2f0f1ec8e17be8402be42c6166db9",

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

@@ -1509,10 +1509,10 @@
         "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": "Readiness is awaited; superseded signals abort before replacement readiness; 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.",
       "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 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.",
       "destruction": "Destruction blocks owner and descendant start/restart; successful destruction destroys owned children. Readiness rejection preserves the documented retry and partial-child boundaries.",
       "diagnostics": [],
       "docs": [
@@ -1569,6 +1569,10 @@
         {
           "file": "test/unit/application-child-lifecycle.spec.js",
           "title": "clears prepared roots beneath already-stopped children without inventing stop hooks"
+        },
+        {
+          "file": "test/unit/application-preparation.spec.js",
+          "title": "notifies before startup, awaits preparation, and forwards one result to completion"
         }
       ],
       "events": [
@@ -1578,16 +1582,25 @@
             "before:stop",
             "before:destroy"
           ],
+          "arguments": [
+            "application",
+            "options"
+          ],
+          "timing": "Synchronous notifications; method and listener return values are not consumed, and returned Promises are neither awaited nor rejection-handled. Preparation follows; start/stop preparation is skipped if the notification supersedes its pending operation. Destruction is terminal and cannot be superseded."
+        },
+        {
+          "names": [
+            "start"
+          ],
           "arguments": [
             "application",
             "options",
-            "context"
+            "result"
           ],
-          "timing": "Only matching onBefore* readiness hook result is awaited; listener return values are ignored."
+          "timing": "Synchronous completion after prepareStart resolves. The prepared result is one unchanged value; return values are ignored."
         },
         {
           "names": [
-            "start",
             "stop",
             "destroy"
           ],
@@ -1595,7 +1608,7 @@
             "application",
             "options"
           ],
-          "timing": "Completion notifications; return values are not awaited."
+          "timing": "Synchronous completion after preparation and teardown; return values are ignored."
         }
       ],
       "members": [
@@ -1603,6 +1616,9 @@
         "stop",
         "restart",
         "destroy",
+        "prepareStart",
+        "prepareStop",
+        "prepareDestroy",
         "onBeforeStart",
         "onBeforeStop",
         "onBeforeDestroy",

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.3`; set `migration_target_version` to
+application. This example inspects `5.0.0-beta.4`; 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.3"
+migration_target_version="5.0.0-beta.4"
 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/agents.md

@@ -122,7 +122,7 @@ means the request was superseded. A current readiness failure rejects. Keep thos
 outcomes distinct. Constructor hooks run synchronously, and completion hooks are synchronous
 notifications; returning a Promise from them does not add readiness.
 
-Pass the readiness hook's signal to cancellable work. After an asynchronous step,
+Pass the preparation method's signal to cancellable work. After an asynchronous step,
 check that it still belongs to the active operation before committing application
 side effects. Marionette suppresses stale lifecycle completion; it cannot undo an
 arbitrary write made by application code. Follow the complete

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

@@ -77,7 +77,7 @@ export function createStatusFeature({ el, state, channel, load, beforeStop = asy
     updateDisplay() {
       this.getView()?.update(this.label, this.getState().get('filter'));
     },
-    async onBeforeStart(app, options, { signal }) {
+    async prepareStart(options, { signal }) {
       this.effects?.dispose();
       // Seed before subscribing. The source is borrowed and survives each run.
       if (state.get('filter') === undefined) { state.set('filter', 'open'); }
@@ -115,7 +115,7 @@ export function createStatusFeature({ el, state, channel, load, beforeStop = asy
       this.showView(new StatusView());
       this.updateDisplay();
     },
-    onBeforeStop(app, options, context) {
+    prepareStop(options, context) {
       // A rejected permission leaves the running feature and its effects intact.
       return beforeStop(options, context);
     },

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

@@ -121,7 +121,7 @@ export async function createResultsFeature({ el, items, loadItems, beforeStop =
         }
       });
     },
-    onBeforeStop(app, options, context) { return beforeStop(options, context); },
+    prepareStop(options, context) { return beforeStop(options, context); },
     onStop() { requests?.dispose(); },
     onBeforeDestroy() { requests?.dispose(); }
   });

package/dist/docs/docs/beta.md

@@ -1,6 +1,6 @@
 # Try Marionette v5 beta
 
-`5.0.0-beta.3` is prepared for application trials. Registry installation requires
+`5.0.0-beta.4` 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,8 +37,9 @@ 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.3 to be published first. Beta.2 remains the previous
-published candidate and does not contain this beta's Application and event contracts.
+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 starter has editable rows, asynchronous local selection, deliberate cancellation,
 and teardown. It has no backend, persistence, or URL router. Connect its `navigate`
@@ -82,7 +83,7 @@ permission, propagation, or trusted-publisher configuration.
 
 ## If the beta fails in your application
 
-Pin `5.0.0-beta.2` across all five packages and restore the matching application
+Pin `5.0.0-beta.3` 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
@@ -91,5 +92,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.2 release. Preserve exact artifacts and failure evidence.
+beta.3 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

@@ -19,7 +19,7 @@ Use plain functions or classes when you do not need Marionette lifecycle, events
 
 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. Readiness is awaited; superseded signals abort before replacement readiness; 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. 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).
 

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.3 @mnjs/data@5.0.0-beta.3
+npm install marionette@5.0.0-beta.4 @mnjs/data@5.0.0-beta.4
 ```
 
 ```javascript