@panphora/hyper-cms 0.4.1 → 0.5.0

package/README.md

@@ -40,6 +40,20 @@ cms.open({ rules: 'collection' })// a tag with data-rules-name~="collection"
 cms.open({ rules: { title: '.title' } })  // a literal rules object, passed by hand
 ```
 
+## Auto-open with `?cms=true`
+
+Load any hypercms page with `?cms=true` in the URL and the CMS opens by itself once the DOM is ready — no trigger, no `cms.open()` call. The auto-open uses the host defaults (`document.body` as both `pageRoot` and `mountTo`), and it never double-mounts: if your page also calls `cms.open()`, the second open is a no-op.
+
+When the user closes the CMS, hypercms rewrites the param to `cms=false` via `history.replaceState` (the param is kept, no reload), so refreshing or sharing the post-close URL does not auto-reopen:
+
+```
+example.com/page?cms=true   →  CMS opens on load
+                            →  user closes
+example.com/page?cms=false  →  refresh / share: stays closed
+```
+
+The rewrite only touches the URL when `cms=true` is actually present; other params and the hash are preserved, and a page opened without a `cms` param never has one injected. Auto-open is ungated — it fires for every visitor, not just the page owner. (A non-owner's edits stay local to their DOM; in a hyperclayjs app the save path shows its "changes are local only" notice.)
+
 ## Hard requirement: `window.hyperclay.Mutation`
 
 hypercms uses [`hyperclayjs`'s Mutation utility](https://github.com/panphora/hyperclayjs/blob/main/src/utilities/mutation.js) as its page-change backend. It's a singleton that already understands `save-ignore`, `save-freeze`, `save-remove`, and `mutations-ignore`, which lets hypercms ignore its own DOM activity without per-event bookkeeping.
@@ -156,10 +170,19 @@ cms.api.removeItem(itemPath)          // drop an item by index
 | `mountTo` | `document.body` | Where the shell DOM mounts. Can be a descendant of pageRoot. |
 | `side` | `'right'` | `'right'` or `'left'`. |
 | `overlay` | `false` | If true, sidebar covers the page; if false, page content gets a padding offset. |
-| `showSaveButton` | `false` | Renders a Save button in the shell footer; clicking dispatches `hcms:save`. |
+| `showSaveButton` | `false` | Renders a Save button in the shell footer. The button carries the `trigger-save` attribute: in hyperclayjs apps the host save system handles the click (with a "changes are local only" notice for non-owners). Standalone hosts delegate it themselves — see below. |
 | `onChange(data, info)` | none | Per-commit callback. |
 | `onError(err)` | none | Per-commit error callback. |
-| `onSave(data)` | none | Save-button callback. |
+
+Standalone `[trigger-save]` handling (no hyperclayjs on the page):
+
+```js
+document.addEventListener('click', (e) => {
+  if (e.target.closest('[trigger-save]')) {
+    persistSomehow(document.documentElement.outerHTML) // or cms.api.getData()
+  }
+})
+```
 
 ### Path syntax
 
@@ -174,10 +197,9 @@ All events dispatch on the shell root and bubble through the document.
 | `hcms:open` | `{ pageRoot }` | After mount, before first interaction. |
 | `hcms:change` | `{ data, path, structural }` | Per successful commit. `structural` is true for add/remove/reorder. |
 | `hcms:error` | `{ error, attemptedData }` | When apply throws (shape mismatch, missing template, etc.). |
-| `hcms:save` | `{ data }` | Save button clicked. |
 | `hcms:close` | `null` | Before teardown. |
 
-`hcms:change` and `hcms:save` are cancelable.
+`hcms:change` is cancelable.
 
 ## Lifecycle