marionette 5.0.0-alpha.2 → 5.0.0-beta.1

package/changelog.md

@@ -1,7 +1,142 @@
-### v5.0.0-alpha.2
+### v5.0.0-beta.1
 
+* Established `@mnjs` as the companion package scope: utils, radio, data, and
+  adapters; the core package remains `marionette`
+* Added a packaged application starter and beta trial guide, plus release
+  authorization restricted to one exact prerelease version
+
+* Added optional `createMarionette()` runtime factories with independent class
+  families, mutable adapters, renderer configuration, and Radio channel registries;
+  ordinary named imports remain one default runtime built through the same composition
+  path
+* Made ESM the canonical distribution for new applications while retaining
+  CommonJS and both UMD outputs as v5 compatibility distributions; UMD and AMD
+  consumers are asked to identify their usage in the public issue tracker before
+  the six-month post-5.0.0 distribution review
+* Added a neutral DataApi for model identity, reads, serialization, ordered
+  model snapshots, entity subscriptions, and structural collection changes
+* Renamed the pre-stable `DataApi.items(collection)` method to
+  `DataApi.models(collection)` without a compatibility alias
+* Renamed the pre-stable serialized collection template property from `items` to
+  `models` without a compatibility alias
+* Changed `Region#show` and `View#showChildView` to require an explicitly
+  constructed View-like instance; template functions, strings, and View-options
+  objects no longer allocate a hidden base View
+* Split the internal View, Region, and declarative Region builder implementations
+  into owner-named modules and removed the obsolete combined source path
+* Added explicit `View#renderAttributes()` and `CollectionView#renderAttributes()`
+  root-attribute refreshes; the default `DomApi.setAttributes` now removes
+  nullish entries while leaving omitted keys untouched
+* Added the optional `@mnjs/data` package with observable Model and ordered
+  Collection sources plus matching DataApi and StateApi adapters
+* Added the optional `@mnjs/adapters` package with explicit Backbone and
+  jQuery subpaths and no root barrel; removed the previous core adapter subpaths.
+  The Backbone integration configures DataApi and StateApi explicitly while
+  preserving native Backbone objects, prototypes, listeners, and event methods;
+  its `models()` method returns a copied ordered snapshot rather than exposing
+  Backbone's mutable internal collection array
+* Changed the default model and collection contract to plain objects and arrays;
+  Backbone-specific data and event shapes now remain inside the explicit
+  `@mnjs/adapters/backbone` integration
+* Removed `children.findByModelCid`; `findByModel` uses the configured DataApi key
+* Replaced the alpha concrete `State` with exact state-source composition and an
+  independent StateApi observation contract; supplied sources are borrowed,
+  `createState(options)` results are owned, and the lazy default is a plain object
+* Changed CollectionView structural updates to render in-place updates, recreate
+  child Views for immutable same-key replacements, drain reentrant observations,
+  recover the latest source after reconciliation hook failures, and move survivor
+  nodes without recreating or rerendering unchanged Views
+* Changed `viewComparator: false` to disable presentation sorting while
+  `sortWithCollection` continues reconciling structural changes to source order;
+  use `sortWithCollection: false` to preserve manually managed child order
+* Moved the optional jQuery-backed DomApi integration to
+  `@mnjs/adapters/dom/jquery`
+  operations and opt-in View, CollectionView, and Behavior `$el` compatibility
+* Require concrete DOM elements for View and CollectionView `el`; resolve
+  selectors and unwrap jQuery collections at the call site
+* Removed the undocumented alpha-only `Behavior#setElement`; retarget
+  Behaviors through their owning View's `setElement` method
+* Fixed CollectionView child identity indexes so prototype-collision cids and
+  same-cid impostors cannot corrupt ownership or mutate unowned Views
+* Fixed removal-only, unfiltered CollectionView updates with default collection
+  ordering or ordering disabled to preserve surviving child DOM, focus, selection,
+  media, and custom-element connection state without firing sort or child-render
+  lifecycles for unchanged survivors
+* Removed the undocumented alpha-only named `Requests` export; request/reply
+  methods remain owned by the built-in `Radio` singleton and its channels
+* Removed the alpha-only request/reply methods from `Application`, `Behavior`,
+  `CollectionView`, `MnObject`, `Region`, and `View`; use `Radio.channel(name)`,
+  the top-level `Radio` API, or an owner's `bindRequests`/`radioRequests`
+  integration instead
+* Fixed selective `unbindRequests` cleanup to preserve a replacement reply
+  owned by another object
 * Fixed Radio circular dependency with log and debug
 * Fixed event interop with Backbone
+* Fixed delegated event matching so nested matching ancestors fire once per event
+* Fixed callable Behavior `events` and `triggers` to resolve after Behavior
+  initialization
+* Fixed CollectionView empty Region construction to occur after `initialize`
+* Removed the module-global feature registry and the `setEnabled` and `isEnabled`
+  exports; configure child event prefixes per View, trigger DOM behavior per
+  trigger, and application-owned values through a state source or explicit configuration
+* Preserved `emptyView` resolver returns of `undefined`, `null`, or `false` as
+  disabled empty-view states
+* Changed the base `Region#show`, `Region#empty`, and `Region#reset`
+  implementations to no-op once Region destruction begins
+* Changed `Region#detachView` once destruction begins to return `undefined`
+  without transferring the current View out of Region-owned teardown
+* Changed destroyed `View#render` and `CollectionView#render` calls to return the
+  instance without resolving templates or running the render lifecycle
+* Changed base `View#setElement` and `CollectionView#setElement` calls once
+  destruction begins to return the instance without changing its element
+* Changed base `CollectionView#addChildView` calls once destruction begins to
+  return the supplied View without inspecting or managing it
+* Changed base `View#delegateEntityEvents` and
+  `CollectionView#delegateEntityEvents` calls once destruction begins to return
+  the instance without resolving host or Behavior maps or binding subscriptions
+* Changed direct `Behavior#delegateEntityEvents` calls once the owning View's
+  destruction begins to return the Behavior without resolving maps or binding
+  subscriptions
+* Changed base `View#bindUIElements`, `CollectionView#bindUIElements`, and
+  direct `Behavior#bindUIElements` calls once the owning View's destruction
+  begins to return the receiver without resolving or binding UI
+* Changed `View#hasRegion` to check own registered Regions without rendering or
+  changing View lifecycle state
+* Changed `View#getRegions` to return a safe Region snapshot without rendering;
+  `View#emptyRegions` remains a render-triggering mutator
+* Changed `View#getRegion` to return an own registered Region without rendering;
+  child View operations now render before dispatching Region lookup overrides
+* Added `Region#getOwner` and `Region#getName` as pure queries over the existing
+  registered View relationship
+* Changed Region registration to treat the existing owner/name relationship as
+  an idempotent no-op and reject conflicting ownership or names with stable
+  diagnostic code `MN0030`
+* Changed named View Region operations to require string names and reject
+  empty names with diagnostic code `MN0032`
+* Changed Application lifecycle operations to return `Promise<boolean>`, added
+  `stop`, `restart`, and `isRunning`, and made later incompatible operations
+  cancel stale lifecycle success without rejecting ordinary cleanup races;
+  readiness hooks receive an operation context with a cooperative abort signal
+* Added explicit named child Application ownership, pure owner-side child
+  queries, and deterministic owner-driven child destruction; parent references
+  remain private lifecycle state rather than public upward lookup
+* Changed owned child Applications to start and stop sequentially with their
+  owner while conflicting direct child operations cancel owner completion
+* Changed Application root View teardown to empty only its current View on stop,
+  destroy constructed Regions, and preserve borrowed host Regions
+* Removed target-first common-method exports from the package root, including
+  their generic plain-object adapter; use the corresponding method on each
+  Marionette instance
+* Trust declared argument shapes for option keys, callbacks, bindings, View and
+  Behavior configuration, and adapter methods; retire their custom shape errors
+  and type private immediate-child propagation as an array
+* Removed the historically documented `Radio.log` and `Radio.debugLog`
+  replacement hooks; the built-in Radio now owns one diagnostic and tuning
+  output path
+* Internalized the Radio Channel constructor and registry; obtain channels
+  through `Radio.channel(name)`
+* Changed borrowed top-level Radio methods to dispatch through the imported
+  singleton instead of accepting an alternate receiver and registry
 
 ### v5.0.0-alpha.1
 

package/dist/agent-skill/SKILL.md

@@ -0,0 +1,79 @@
+---
+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.
+---
+
+# 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.
+
+## Find the contract
+
+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.
+
+Run the bundled helper with Node 24 or later (replace both absolute paths):
+
+```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
+```
+
+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`.
+
+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.

package/dist/agent-skill/scripts/docs.mjs

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+const usage = 'Usage: node docs.mjs [--project PATH] [--package-root PATH] [--list | --page SOURCE]';
+const hash = value => createHash('sha256').update(value).digest('hex');
+const json = async path => JSON.parse(await readFile(path, 'utf8'));
+
+async function installedPackage(project) {
+  let directory = await realpath(project);
+  if (!(await stat(directory)).isDirectory()) {
+    throw new Error('--project must name a directory.');
+  }
+  while (true) {
+    const candidate = resolve(directory, 'node_modules/marionette');
+    try {
+      return await realpath(candidate);
+    } catch (error) {
+      if (error.code !== 'ENOENT') { throw error; }
+    }
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new Error('No installed marionette found. Use the application workspace or --package-root for its physical package directory.');
+    }
+    directory = parent;
+  }
+}
+
+async function main() {
+  const options = { project: process.cwd() };
+  const args = process.argv.slice(2);
+  let mode;
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index];
+    if (argument === '--help') { console.log(usage); return; }
+    if (argument === '--list') {
+      if (mode) { throw new Error(usage); }
+      mode = 'list';
+    } else if (['--project', '--package-root', '--page'].includes(argument)) {
+      const value = args[++index];
+      if (!value || value.startsWith('--')) { throw new Error(usage); }
+      if (argument === '--page') {
+        if (mode) { throw new Error(usage); }
+        mode = 'page';
+      }
+      options[argument.slice(2)] = value;
+    } else {
+      throw new Error(usage);
+    }
+  }
+  const packageRoot = options['package-root'] ? await realpath(options['package-root']) : await installedPackage(options.project);
+  const metadata = await json(resolve(packageRoot, 'package.json'));
+  const docsRoot = await realpath(resolve(packageRoot, 'dist/docs')).catch(() => {
+    throw new Error('This package has no dist/docs. Read its exports/declarations and obtain documentation from its exact release or known source revision; do not substitute current master.');
+  });
+  const docsLocal = relative(packageRoot, docsRoot);
+  if (docsLocal === '..' || docsLocal.startsWith(`..${sep}`) || isAbsolute(docsLocal)) {
+    throw new Error('Documentation root escapes its package.');
+  }
+  const manifest = await json(resolve(docsRoot, 'manifest.json'));
+  if (metadata.name !== 'marionette' || manifest.packageName !== metadata.name || manifest.packageVersion !== metadata.version) {
+    throw new Error('Documentation package/version does not match the installed marionette package.');
+  }
+  if (manifest.schemaVersion !== 1 || !/^[a-f0-9]{40}$/.test(manifest.sourceRevision) ||
+      typeof manifest.sourceDirty !== 'boolean' || !Array.isArray(manifest.pages) || !Array.isArray(manifest.assets)) {
+    throw new Error('Unsupported or incomplete documentation manifest.');
+  }
+  const entries = [...manifest.pages, ...manifest.assets];
+  const files = new Map();
+  for (const entry of entries) {
+    const source = entry.source;
+    if (typeof source !== 'string' || isAbsolute(source) || source.includes('\\') || source.split('/').some(part => !part || part === '..' || part === '.')) {
+      throw new Error('Unsafe documentation source path.');
+    }
+    if (files.has(source)) { throw new Error(`Duplicate documentation source: ${source}`); }
+    const path = await realpath(resolve(docsRoot, source));
+    const local = relative(docsRoot, path);
+    if (local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+      throw new Error(`Documentation source escapes its package: ${source}`);
+    }
+    const content = await readFile(path);
+    if (hash(content) !== entry.sha256) { throw new Error(`Documentation hash mismatch: ${source}`); }
+    files.set(source, { path, content });
+  }
+  const digest = hash(entries.sort((a, b) => a.source.localeCompare(b.source, 'en'))
+    .map(entry => `${entry.source}\0${entry.sha256}\n`).join(''));
+  if (digest !== manifest.contentSha256) { throw new Error('Documentation manifest content digest does not match.'); }
+  const provenance = {
+    packageRoot,
+    packageVersion: metadata.version,
+    sourceRevision: manifest.sourceRevision,
+    sourceDirty: manifest.sourceDirty,
+    contentSha256: digest,
+  };
+  if (mode === 'page') {
+    const page = manifest.pages.find(entry => entry.source === options.page);
+    if (!page) { throw new Error('Page is not in this package manifest. Use --list to find its exact source path.'); }
+    console.log(JSON.stringify({ ...provenance, source: page.source, sha256: page.sha256 }));
+    console.log(files.get(page.source).content.toString('utf8'));
+  } else {
+    console.log(JSON.stringify({ ...provenance, pages: manifest.pages.map(page => ({
+      source: page.source, title: page.title, section: page.section, path: files.get(page.source).path,
+    })) }, null, 2));
+  }
+}
+
+main().catch(error => {
+  console.error(`Marionette docs: ${error.message}`);
+  process.exitCode = 1;
+});