marionette 5.0.0-beta.2 → 5.0.0-beta.4

package/changelog.md

@@ -1,3 +1,48 @@
+### 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
+
+> Fewer surprise events and surprise startups, because whitespace is not an API and ownership is not a scheduler.
+
+* Add `Application#setView(view)` and no-argument `showView()` so an Application
+  can compose a complete root View tree before handing it to its Region. `getView()`
+  returns the prepared View first and the displayed View after handoff.
+* Make child Application activation explicit. Registration owns teardown without
+  starting children; parent restart does not automatically reactivate registered children.
+  Successful stop and destruction drain active descendants through stopped owners,
+  and descendant `start()` or `restart()` resolves `false` while an ancestor is
+  stopping or terminal.
+* Resolve `triggerMethod` lifecycle hooks from instance and prototype methods only;
+  constructor-option hooks no longer override or suppress those methods.
+* Treat Events and Radio request names as literal strings across registration,
+  dispatch, and removal. Replace whitespace-batched operations with separate calls
+  or map entries; object-form event dispatch and the shared `eventSplitter` export
+  are removed.
+* Remove View Region registration/removal lifecycle events. Observe a specific
+  Region's destruction lifecycle when teardown notification is required.
+* Fix `getOption` so numeric zero and empty-string property keys resolve through
+  the normal option-before-instance lookup.
+* Clarify selector-backed versus Element-backed Region placeholder identity after
+  a parent render, with public regression coverage for replacement and cleanup.
+* Improve the typed starter's View ownership and missing-field rendering, and add
+  consumer-first migration and native/Backbone routing guidance.
+* Add executable Application guidance for explicit effect lifetimes, navigation,
+  and latest-request refreshes that preserve active View and row identity.
+
 ### v5.0.0-beta.2
 
 > Now with source maps, so “the AI wrote it” is slightly less useful as a debugging strategy.

package/dist/agent-skill/SKILL.md

@@ -1,89 +1,75 @@
 ---
 name: marionette
-description: Build and debug applications using Marionette v5 with the installed version's documentation, independent integration choices, and lifecycle-aware validation. Use for application work involving Marionette Views, Regions, CollectionViews, Application, state, or adapters; library maintenance follows its own repository instructions.
+description: Build or debug Marionette v5 applications using version-matched docs. For changes to the library itself, use its repository guidance.
 ---
 
 # Build with Marionette
 
-Use the application's installed contract. This skill does not select a package
-version, authorize an upgrade, or replace the application's existing decisions.
+Use the application's installed contract and preserve compatible integration
+choices. This skill does not authorize dependency upgrades.
 
-## Find the contract
+## Locate matching docs
 
-Inspect the application's manifest, lockfile, and runtime configuration. Resolve
-paths relative to the application being edited, including its workspace directory
-in a monorepo. Do not use the skill's own directory as the application root.
+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.
+Its path is `scripts/docs.mjs` relative to the directory containing this `SKILL.md`:
 
-Run the bundled helper with Node 24 or later (replace both absolute paths):
+- 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
 ```
 
-The helper reads files only. It finds the installed `marionette` package without
-executing project code, checks the packaged documentation's version and hashes,
-and reports provenance. Use its returned paths to read further pages. It does not
-search the internet or run a package manager. For an installation without a
-`node_modules` tree, supply `--package-root /physical/path/to/marionette` obtained
-from that project's package manager. Do not substitute a different workspace's
-package just because it is available.
-
-If the installed artifact has no `dist/docs`, inspect its exports and declarations
-and obtain docs from that package's exact release or known source commit. An alpha
-version string alone does not establish a source match. Report missing provenance;
-do not silently use `master`, current website docs, or another project's package.
-A hash check detects inconsistent documentation files, not whether a custom build's
-JavaScript actually matches those docs. Validate uncertain behavior against the
-installed runtime. A `sourceDirty: true` manifest describes local changes, not an
-immutable release.
-
-## Read only what the task needs
-
-Start with packaged `docs/agents.md`, then use these source paths from the manifest:
-
-- New setup or an integration decision: `docs/installation.md` and
-  `docs/choosing-integrations.md`.
-- UI ownership and replacement: `docs/marionette.view.md`,
-  `docs/marionette.region.md`, and `docs/view.lifecycle.md`.
-- Changing lists: `docs/marionette.collectionview.md` and `docs/data.api.md`.
-- Asynchronous features or routing: `docs/marionette.application.md` and
-  `docs/routing.md`.
-- State or a diagnostic: `docs/marionette.state.md` or
-  `docs/diagnostic-catalog.md`.
-
-If the client already has the Marionette documentation MCP configured, consult
-the `marionette://catalog` resource before searching. Use remote documents only
-when version and source match this installation. Pass the exact installed
-`version` to every tool and follow `nextOffset` until it is `null` to retrieve the
-complete page or example.
-Setup instructions: https://marionettejs.com/docs/mcp/. A URL in these instructions
-does not install an MCP connection. Keep the installed docs when the catalog is
-unsupported or the service is unavailable. Website WebMCP only controls its own
-examples, not this application.
-
-The manifest is the available-page index. Follow direct links for the selected
-task instead of loading the whole reference. For v4 work, use matching migration
-material and installed APIs; these v5 instructions are not an upgrade plan.
-
-## Make the application decision
-
-Preserve a compatible established integration. For a new application, use built-in
-behavior when it supplies the capability; select an observable source when updates
-need observation. Choose DataApi, StateApi, renderer, DomApi, EventDelegator, and
-router independently. A Backbone router does not require Backbone data or state.
-Register configuration before creating its consumers; use an isolated runtime only
-when independent configurations must coexist.
-
-Name the owner and cleanup operation for Views, subscriptions, widgets, and async
-work. Use public lifecycle APIs. Check stale work before committing side effects;
-framework cancellation cannot undo arbitrary writes by application code. Consult
-the current reference for exact return and readiness behavior rather than inferring
-it from a method name.
-
-Use the application's own test commands. Exercise the requested behavior and its
-relevant boundary: stale navigation, surviving edits/focus, rerendered event
-handlers, or resource cleanup. Browser behavior needs a browser check. Report
-commands actually run and untested boundaries; a successful build is not proof of
-those interactions. Record changed integration decisions in the application's own
-instructions without copying the library's maintainer policy.
+These are lookup options, not a required sequence. `--list` returns provenance and
+available page paths; `--page` reads one source path. The helper checks packaged
+documentation hashes and version without executing project code or using a network.
+For installations without `node_modules`, supply `--package-root` with the physical
+package directory obtained from that application's package manager.
+
+If packaged docs are absent, use the exact release or known source commit and
+installed exports/declarations. Do not silently substitute current website docs,
+`master`, or another workspace's package. An alpha version alone does not establish
+source identity; `sourceDirty: true` is not an immutable release. Documentation
+hashes do not prove a custom runtime matches them; test uncertain runtime behavior.
+
+## Select the relevant contract
+
+Pass the task page's `source` field from the manifest or `--list` output to
+`--page`. The returned absolute `path` is for reading the file directly:
+
+| Task | Packaged page |
+| --- | --- |
+| New application | `docs/development.md` for the typed starter; `docs/choosing-integrations.md` for integration decisions |
+| Migrating an existing application | `docs/agent-tools.md` (pre-migration setup); `docs/migration-from-v4.md` and `upgradeGuide.md` from that target |
+| Application architecture or unfamiliar ownership | `docs/agents.md` |
+| Rendering or screen replacement | `docs/marionette.view.md`, `docs/marionette.region.md`, `docs/view.lifecycle.md` |
+| Changing lists or observable records | `docs/marionette.collectionview.md`, `docs/data.api.md` |
+| Async features or navigation | `docs/marionette.application.md`, `docs/routing.md` |
+| State ownership or framework error | `docs/marionette.state.md` or `docs/diagnostic-catalog.md` |
+| Skill setup or optional documentation MCP | `docs/agent-tools.md` |
+
+Follow relevant links rather than loading an overview and every reference. For MCP,
+read the retrieval rules in `docs/agent-tools.md` before remote use: exact version
+and source must match. Installed Markdown remains sufficient. For v4 applications,
+use matching migration material and installed APIs; this skill is not an upgrade plan.
+
+DataApi, StateApi, renderer, DomApi, EventDelegator, and router are independent
+choices; a Backbone router does not require Backbone data. Register configuration
+before consumers. Use templates, named Regions, and public lifecycle APIs; domain
+records belong in data sources, not child View traversal. For application design,
+including personalized examples, use `docs/agents.md`.
+
+## Completion
+
+The requested application behavior works against the installed package, preserves
+unrelated edits/focus and ownership, and has evidence for the affected interaction
+and cleanup boundary. Use the application's checks; browser interactions require
+browser evidence. Report actual results and untested boundaries. Record changed
+integration decisions in the application's notes, keeping API details in the docs.