jops-core 1.1.0 → 1.1.1

package/README.md

@@ -54,7 +54,14 @@ The import map lets your app modules use `import { View } from "jops-core"`. The
 
 `App.js` is your entry point — a file you provide that instantiates your root `View` and mounts it to the page. Point `data-app` to wherever you place it.
 
-Replace `@latest` with a specific version (e.g. `@1.0.4`) to pin. No build step, no npm, no bundler.
+Replace `@latest` with a specific version (e.g. `@1.1.1`) to pin. No build step, no npm, no bundler.
+
+By default the app renders into `<body>`. To render it into an element instead (keeping the rest of the page), add `data-root` with the element's id:
+
+```html
+<div id="app"></div>
+<script type="module" src="https://cdn.jsdelivr.net/npm/jops-core@latest/lib/jops-core.min.js" data-app="./src/App.js" data-root="app"></script>
+```
 
 > **Note:** ES modules require an HTTP server — open your project with `npx serve` (or any static server) rather than double-clicking `index.html`. Browsers block `import` on `file://` URLs.
 
@@ -378,17 +385,33 @@ The root `<div>` has `position: relative`, which the Router's slide and fade ani
 - **Next.js owns the CSS.** `setStyle()` has no effect inside Next.js (a console message says so once). Tailwind CSS v4 also scans the files in `public/`, so Tailwind classes in JOPS layouts and views are generated by the Next.js build. Write class names as complete literal strings (`"bg-sky-50"`, never `` `bg-${color}-50` ``). Put other CSS in `globals.css` or a CSS file imported by the page, scoped under the app's root class (`.my-app table td { … }`), since it applies to the whole site.
 - **Backend calls:** `fetch("/api/…")` to Route Handlers on the same origin; the session cookie is sent automatically. A JOPS app can't call Server Actions.
 - **One JOPS app per page.** `Router`, `Store` and `EventBus` are page-wide singletons.
+- **Always use `JopsApp` inside a Next.js page.** Don't add the jops-core `<script>` or an import map to a page or layout yourself: React doesn't run scripts it renders on soft navigation, and nothing would end the app when the page is left.
+
+### Deploying
+
+The result is a standard Next.js app: `npm run build` produces `.next/`, and it runs on a Node.js server when it uses server features such as Route Handlers. Deploy it like any Next.js app (see the [Next.js deployment docs](https://nextjs.org/docs/app/getting-started/deploying)). Points specific to JOPS:
+
+- **Deploy `public/` with the app**: the whole JOPS app and the library live there. With `output: "standalone"`, copy `public/` (and `.next/static/`) into `.next/standalone/` yourself.
+- **Caching:** files in `public/` are not content-hashed, so a CDN or the browser may keep serving an old `jops-core.min.js` or view after a deploy. Use short cache headers for those paths, or versioned paths.
+- **Library version:** run `npx jops-core update` after updating the package and before `npm run build`.
+
+---
+
+## Embedding JOPS in Other Pages (Hosted Mode)
 
-### Without React: hosted mode
+A JOPS app can run inside any page that is not a React component: a plain HTML page, or a page rendered by another server framework (PHP, ASP.NET, Rails, Django, …). This is the mechanism `JopsApp` uses in Next.js; **inside a Next.js page, use `JopsApp`** instead (see [Next.js Integration](#nextjs-integration)).
 
-`JopsApp` uses hosted mode, which any host page can use directly. Load the library with `data-host` and no `data-app`: nothing starts automatically, and `window.JOPS` exposes `mount()` and `unmount()` (a `jops:ready` event fires when it is available):
+Load the library with `data-host` and no `data-app`: nothing starts automatically, and `window.JOPS` exposes `mount()` and `unmount()` (a `jops:ready` event fires when it is available). The import map and the script `src` must be the same URL, so the page has a single jops-core instance.
 
 ```html
-<script type="importmap">{ "imports": { "jops-core": "/lib/jops-core.min.js" } }</script>
-<script type="module" src="/lib/jops-core.min.js" data-host></script>
+<script type="importmap">
+  { "imports": { "jops-core": "https://cdn.jsdelivr.net/npm/jops-core@latest/lib/jops-core.min.js" } }
+</script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/jops-core@latest/lib/jops-core.min.js" data-host></script>
+
 <div id="app" style="position: relative"></div>
 <script type="module">
-  const start = () => window.JOPS.mount({ app: "/my-app/App.js", root: document.getElementById("app") });
+  const start = () => window.JOPS.mount({ app: "./my-app/App.js", root: document.getElementById("app") });
   window.JOPS ? start() : window.addEventListener("jops:ready", start, { once: true });
 </script>
 ```
@@ -396,24 +419,12 @@ The root `<div>` has `position: relative`, which the Router's slide and fade ani
 | Function | Description |
 | --- | --- |
 | `mount({ app, root })` | Imports `app` and creates its default export; the root view renders into `root` (an `HTMLElement`) instead of `<body>`. Returns a promise of the App instance |
-| `unmount()` | Ends the app completely (see "App lifecycle" above). Safe to call more than once; `mount()` can start an app again afterwards |
-
-Both are also exported by the module (`import { mount, unmount } from "jops-core"`) for modules running on the same page. In hosted mode the Android back button integration is off.
-
-A **standalone** app (started by `data-app`) can render into an element instead of `<body>` with `data-root`:
-
-```html
-<div id="app"></div>
-<script type="module" src="/lib/jops-core.min.js" data-app="./src/App.js" data-root="app"></script>
-```
-
-### Deploying
-
-The result is a standard Next.js app: `npm run build` produces `.next/`, and it runs on a Node.js server when it uses server features such as Route Handlers. Deploy it like any Next.js app (see the [Next.js deployment docs](https://nextjs.org/docs/app/getting-started/deploying)). Points specific to JOPS:
+| `unmount()` | Ends the app completely: destroys the Router and every view, empties `root`, clears `Store` and `EventBus`, and restores the history methods JOPS wrapped. Safe to call more than once; `mount()` can start an app again afterwards |
 
-- **Deploy `public/` with the app**: the whole JOPS app and the library live there. With `output: "standalone"`, copy `public/` (and `.next/static/`) into `.next/standalone/` yourself.
-- **Caching:** files in `public/` are not content-hashed, so a CDN or the browser may keep serving an old `jops-core.min.js` or view after a deploy. Use short cache headers for those paths, or versioned paths.
-- **Library version:** run `npx jops-core update` after updating the package and before `npm run build`.
+- **Paths depend on where the library comes from.** With the library from the CDN (as above), JOPS resolves paths relative to the **hosting page**: `./my-app/App.js` on `example.com/admin/users` means `example.com/admin/my-app/App.js`, and root-absolute `/my-app/...` paths are turned page-relative too. With a vendored library on the same origin (`/lib/jops-core.min.js` in both the import map and `src`), write root-absolute paths (`/my-app/App.js`, `src="/my-app/Users.js"`), which work on every page.
+- **Ending the app:** a full page load ends it anyway. A host that removes the app's element without a page load, or navigates with `history.pushState()`, calls `unmount()`; when history moves to another path the Router also ends the app by itself.
+- `mount` and `unmount` are also exported by the module (`import { mount, unmount } from "jops-core"`) for modules running on the same page.
+- In hosted mode `setStyle()` has no effect (the host page provides the CSS) and the Android back button integration is off.
 
 ---
 
@@ -819,7 +830,7 @@ Prefer the owned form inside views. A global subscription made by a view keeps t
 
 ### `mount()` / `unmount()` — Functions
 
-Start and end an app in a host page (hosted mode). Used by `JopsApp` in Next.js; see [Without React: hosted mode](#without-react-hosted-mode). The page must load jops-core with `data-host` (otherwise it starts `data-app` / `./src/App.js` by itself); `window.JOPS.mount` / `window.JOPS.unmount` are the same functions.
+Start and end an app in a host page (hosted mode). Used by `JopsApp` in Next.js; see [Embedding JOPS in Other Pages](#embedding-jops-in-other-pages-hosted-mode). The page must load jops-core with `data-host` (otherwise it starts `data-app` / `./src/App.js` by itself); `window.JOPS.mount` / `window.JOPS.unmount` are the same functions.
 
 ```js
 import { mount, unmount } from "jops-core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jops-core",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A no-bundler, OOP-first SPA framework with Android-style view composition",
   "type": "module",
   "exports": {