jops-core 1.0.12 → 1.0.13

package/README.md

@@ -117,6 +117,166 @@ This gives you HTML syntax highlighting, Emmet, and autocomplete inside every ``
 
 ---
 
+## Hybrid Mobile Apps (Cordova, Ionic & Capacitor)
+
+JOPS runs unchanged inside a mobile WebView, so the same app can ship to the iOS App Store and Google Play through a hybrid shell. Nothing on this page affects JOPS in a regular browser: every mobile adjustment is either feature-detected (it only runs when the native shell is present) or a CSS value that resolves to `0` outside it.
+
+| Shell | Status |
+| --- | --- |
+| Apache Cordova (iOS + Android) | Supported and tested (cordova-ios 8, cordova-android 15) |
+| Capacitor (iOS + Android) | Supported and tested (Capacitor 8) — install `@capacitor/app` for the Android back button |
+| Ionic | Use Ionic's framework-free UI components (`@ionic/core`) on top of Cordova or Capacitor. `ionic start` always scaffolds an Angular, React or Vue app, which JOPS is not meant to be combined with — start from a plain Cordova or Capacitor project instead |
+
+### Setup order
+
+**1. Create the hybrid project and its platforms.**
+
+```bash
+# Cordova
+cordova create my-app com.example.myapp MyApp
+cd my-app
+cordova platform add ios android
+```
+
+```bash
+# Capacitor
+mkdir my-app && cd my-app
+npm init -y
+npm i @capacitor/core @capacitor/ios @capacitor/android @capacitor/app
+npm i -D @capacitor/cli
+npx cap init MyApp com.example.myapp --web-dir www
+npx cap add ios
+npx cap add android
+```
+
+**2. Install JOPS in the project root** — the folder with `package.json`, *not* inside `www/`. Cordova and Capacitor copy the whole web folder into the app, so a `node_modules/` there would be bundled too.
+
+```bash
+npm i jops-core
+```
+
+**3. Run `init` from the project root** (running it from inside `www/` / your `webDir` works too):
+
+```bash
+npx jops-core init
+```
+
+`init` detects the project type and writes the app into the web folder that the shell actually serves — `www/` for Cordova, the `webDir` from `capacitor.config.*` for Capacitor:
+
+```
+[jops-core] Detected cordova project → web folder: www/
+```
+
+**4. Build and run** with the shell's own tools: `cordova run ios` / `cordova run android`, or `npx cap sync` followed by `npx cap run ios` / `npx cap run android` (or open the native project in Xcode / Android Studio).
+
+### What `npx jops-core init` configures
+
+| | Web | Cordova | Capacitor |
+| --- | --- | --- | --- |
+| `index.html`, `lib/`, template | current folder | `www/` | `webDir` |
+| `.vscode/` and `package.json` scripts | current folder | project root | project root |
+| `viewport-fit=cover` | — | ✓ | ✓ |
+| Content-Security-Policy | — | adds `'unsafe-inline'` (inline import map) and `blob:` (`Thread` workers) to `script-src` | — (Capacitor has none by default) |
+| `<script src="cordova.js">` | — | ✓ | — |
+| iOS custom scheme in `config.xml` | — | ✓ (`app://localhost`) | — (Capacitor uses `capacitor://localhost`) |
+| `"build"` script in `package.json` | ✓ | — (use `cordova build`) | — (use `npx cap sync`) |
+| `"postinstall": "npx jops-core init"` | ✓ | ✓ | ✓ |
+
+- Every step checks first, so running `init` again — including through `postinstall` — never duplicates anything.
+- **Cordova's sample page:** when you pick the *Empty* or *Hello World* template and `www/index.html` is still the page created by `cordova create`, `init` renames it to `www/index.cordova.html` and writes a JOPS `index.html` instead (the sample's `js/index.js` expects markup that a JOPS app replaces). No files are deleted; `css/`, `img/` and `js/` from the sample can be removed by hand.
+- **iOS scheme (Cordova):** JOPS loads `App.js`, views and layouts with native `import()` and `fetch()`, which WebViews block on `file://` pages. Cordova Android and Capacitor already serve from `https://localhost`; for Cordova iOS, `init` adds the following to `config.xml` (applied on the next `cordova prepare` / `build` / `run`):
+
+  ```xml
+  <platform name="ios">
+      <preference name="scheme" value="app" />
+      <preference name="hostname" value="localhost" />
+  </platform>
+  ```
+
+  Values you already set are never changed — any custom scheme works. `init` warns if the iOS scheme is `file`, `http` or `https`, or if `AndroidInsecureFileModeEnabled` is `true`, since both keep the app on `file://`. **Already-published apps:** the new origin cannot see data stored under `file://` (localStorage, IndexedDB), so plan a migration if your app stores data locally.
+- `npx jops-core update` writes to the same web folder, and `npx jops-core build` is skipped in hybrid projects (the web folder is shipped as-is).
+- Override the detection with `--cordova`, `--capacitor` or `--web` (for example `npx jops-core init --web` to treat the current folder as a plain web app).
+
+For reference, the `index.html` that `init` produces for a new Cordova project:
+
+```html
+<head>
+  <meta charset="UTF-8" />
+  <meta http-equiv="Content-Security-Policy"
+        content="default-src 'self' data: blob: https://ssl.gstatic.com; script-src 'self' 'unsafe-inline' blob:; style-src 'self' 'unsafe-inline'; connect-src 'self' data: blob:; media-src * blob:; img-src 'self' data: blob: content:;" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+  <script type="importmap">
+    { "imports": { "jops-core": "/lib/jops-core.min.js" } }
+  </script>
+</head>
+<body>
+  <script src="cordova.js"></script>
+  <script type="module" src="/lib/jops-core.min.js" data-app="./src/App.js"></script>
+</body>
+```
+
+### Android back button
+
+In Cordova and Capacitor, JOPS connects the Android back button (key and gesture) to the Router automatically:
+
+- If `Router.singleton().canGoBack()` is `true`, it calls `Router.back()` — the current view receives `onBackPressed()` exactly as with browser back.
+- On the first screen, it closes the app (`navigator.app.exitApp()`), the standard Android behaviour.
+
+This is required on Android 16 (`targetSdk 36`, predictive back): without a `backbutton` listener, Cordova lets the system handle back and the app closes on the first press regardless of history. It also smooths over a cordova-android 15 issue where one key press fires `backbutton` twice.
+
+The hook only activates on the `deviceready` event, which Cordova and Capacitor fire and a regular browser never does. If your app handles `backbutton` itself, turn the built-in handler off:
+
+```html
+<script type="module" src="/lib/jops-core.min.js" data-app="./src/App.js" data-native-back="off"></script>
+```
+
+**Capacitor:** install the official App plugin — no code is needed:
+
+```bash
+npm i @capacitor/app
+npx cap sync
+```
+
+Capacitor's Cordova compatibility layer fires `deviceready` and forwards JOPS's `backbutton` listener to the plugin, so the behaviour above applies unchanged. Without `@capacitor/app`, Capacitor does not intercept back at all and the app closes on the first press; JOPS logs a console warning in that case.
+
+> **Do not** also register `App.addListener("backButton", ...)` while the built-in handler is on: the plugin calls your listener *and* fires `backbutton`, so every press would go back twice.
+
+To handle back yourself in Capacitor, opt out with `data-native-back="off"` and use the plugin's global (no bundler needed):
+
+```js
+const { App } = window.Capacitor.Plugins;
+
+App.addListener("backButton", () => {
+  const router = Router.singleton();
+  if (router?.canGoBack()) router.back();
+  else App.exitApp();
+});
+```
+
+### Notches, Dynamic Island and the home indicator
+
+With `viewport-fit=cover` (added by `npx jops-core init` in Cordova and Capacitor projects) the page extends under the status bar and the home indicator. Pad fixed or sticky bars with the safe-area insets — they are `0` in a regular browser, so the layout is unchanged there:
+
+```css
+.header {
+  padding-top: calc(1rem + env(safe-area-inset-top, 0px));
+}
+.footer {
+  padding-bottom: calc(2rem + env(safe-area-inset-bottom, 0px));
+}
+```
+
+The Hello World template already does this.
+
+### Debugging
+
+- **Android:** open `chrome://inspect` in desktop Chrome while the emulator or a device runs the debug build.
+- **iOS:** Safari → Develop → *Simulator* → your app.
+
+A `cordova_plugins.js` "not found" error in the console is expected when the project has no Cordova plugins installed; it is harmless.
+
+---
+
 ## Class Reference
 
 ### `View` — Base Class
@@ -138,7 +298,7 @@ export default class MyView extends View { ... }
 | `async onLayout()`        | DOM is live — add subviews, read initial data                                  |
 | `async onResume()`        | View becomes visible — called on first display and on every return navigation  |
 | `bindEvents()`            | Wires `on*` attributes on `[jops-event-bind]` elements to class methods |
-| `onBackPressed()`         | Called by Router when back navigation is detected on this view                 |
+| `onBackPressed()`         | Called by Router when the user navigates back from this view (browser back, `Router.back()`, Android back button in hybrid apps) — never on forward navigation |
 
 #### Instance Methods
 
@@ -266,6 +426,7 @@ Hash-based SPA router. Singleton. Declared in the layout as `<Router jops animat
 | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `navigate(path, ClassDef?)` | Creates a new view instance for `path`, pushes onto the nav stack, animates forward. Updates address bar to `#path?params`. `ClassDef` required for dynamic routes not in the static route map |
 | `back()`                    | Navigates back — pops the nav stack with animation if non-empty, otherwise calls `history.back()`                                                                                              |
+| `canGoBack()`               | Returns `true` if there is an earlier JOPS history entry to go back to (like checking the back stack in Android)                                                                              |
 | `replace(path, ClassDef?)`  | Clears the nav stack and navigates to `path`. Uses existing flat route instance if available, otherwise creates a new one from `ClassDef`                                                      |
 | `getParams()`               | Returns the current URL query params as a plain object. Works for both static (`href="#path?k=v"`) and dynamic (`navigate("/path?k=v")`) routes                                                |
 
@@ -393,9 +554,11 @@ t.terminate();
 
 | Command                | Description                                                                |
 | ---------------------- | -------------------------------------------------------------------------- |
-| `npx jops-core init`   | Vendor library, configure `index.html`, inject scripts into `package.json` |
+| `npx jops-core init`   | Vendor library, configure `index.html`, inject scripts into `package.json`. Detects Cordova and Capacitor projects (see [Hybrid Mobile Apps](#hybrid-mobile-apps-cordova-ionic--capacitor)) |
 | `npx jops-core update` | Copy the latest `jops-core.min.js` from `node_modules` to `lib/`          |
-| `npx jops-core build`  | Generate production-ready `dist/` folder                                   |
+| `npx jops-core build`  | Generate production-ready `dist/` folder (skipped in Cordova/Capacitor projects) |
+
+`init` and `update` accept `--cordova`, `--capacitor` or `--web` to override the detected project type.
 
 ---
 

package/bin/init.js

@@ -4,18 +4,71 @@ import path from "path";
 import readline from "readline";
 import { fileURLToPath } from "url";
 
-const [,, command] = process.argv;
+const [,, command, ...flags] = process.argv;
 
 if (command !== "init" && command !== "build" && command !== "update") {
   console.log("Usage:");
   console.log("  npx jops-core init    — vendor library and configure index.html");
   console.log("  npx jops-core update  — copy the latest jops-core.min.js to lib/");
   console.log("  npx jops-core build   — generate production-ready dist/ folder");
+  console.log("");
+  console.log("Options (init, update):");
+  console.log("  --cordova | --capacitor | --web   override the detected project type");
   process.exit(0);
 }
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const consumerRoot = process.cwd();
+
+// ─── project detection ───────────────────────────────────────────────────────
+// projectRoot: package.json, .vscode/   webRoot: index.html, lib/, src/
+// They differ in hybrid projects: Cordova serves www/, Capacitor serves its webDir.
+
+const forced = ["--cordova", "--capacitor", "--web"]
+  .find((f) => flags.includes(f))?.slice(2);
+
+function readCapacitorWebDir(dir) {
+  for (const name of ["capacitor.config.json", "capacitor.config.ts", "capacitor.config.js"]) {
+    const p = path.join(dir, name);
+    if (!fs.existsSync(p)) continue;
+    const text = fs.readFileSync(p, "utf8");
+    if (name.endsWith(".json")) return JSON.parse(text).webDir ?? "www";
+    return text.match(/webDir\s*:\s*["'`]([^"'`]+)["'`]/)?.[1] ?? "www";
+  }
+  return null;
+}
+
+function isCordovaRoot(dir) {
+  const p = path.join(dir, "config.xml");
+  return fs.existsSync(p) && /<widget\b/.test(fs.readFileSync(p, "utf8"));
+}
+
+// Returns { type, webRoot } when `dir` is a hybrid project root, otherwise null.
+// Capacitor first: a project migrated from Cordova may still contain config.xml.
+function detectHybrid(dir) {
+  const webDir = readCapacitorWebDir(dir);
+  if (webDir) return { type: "capacitor", webRoot: path.resolve(dir, webDir) };
+  if (isCordovaRoot(dir)) return { type: "cordova", webRoot: path.join(dir, "www") };
+  return null;
+}
+
+function resolveProject(cwd) {
+  if (forced !== "web") {
+    const here = detectHybrid(cwd); // run from the project root
+    if (here) return { type: forced ?? here.type, projectRoot: cwd, webRoot: here.webRoot };
+    // Run from inside www/ (or a nested webDir such as dist/app): find the nearest project root above.
+    for (let dir = path.dirname(cwd); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+      const up = detectHybrid(dir);
+      if (!up) continue;
+      if (up.webRoot === cwd) return { type: forced ?? up.type, projectRoot: dir, webRoot: cwd };
+      break;
+    }
+  }
+  return { type: forced ?? "web", projectRoot: cwd, webRoot: cwd };
+}
+
+const { type, projectRoot, webRoot } = resolveProject(process.cwd());
+const isHybrid = type !== "web";
+const rel = (p) => path.relative(projectRoot, p) || ".";
 
 function copyDir(src, dest) {
   const SKIP = new Set(["node_modules", "dist", ".git", "package.json", "package-lock.json", ".DS_Store"]);
@@ -30,22 +83,124 @@ function copyDir(src, dest) {
       copyDir(srcPath, destPath);
     } else if (!fs.existsSync(destPath)) {
       fs.copyFileSync(srcPath, destPath);
-      console.log(`[jops-core] Created ${path.relative(consumerRoot, destPath)}`);
+      console.log(`[jops-core] Created ${rel(destPath)}`);
     }
   }
 }
 
+// ─── index.html helpers (hybrid projects) ────────────────────────────────────
+
+// Same policy as Cordova's default, plus 'unsafe-inline' for the inline import map
+// and blob: for Thread workers.
+const CORDOVA_CSP =
+  "default-src 'self' data: blob: https://ssl.gstatic.com; script-src 'self' 'unsafe-inline' blob:; " +
+  "style-src 'self' 'unsafe-inline'; connect-src 'self' data: blob:; media-src * blob:; " +
+  "img-src 'self' data: blob: content:;";
+
+// Let the page extend under the notch; safe-area CSS takes care of padding.
+function ensureViewportFitCover(html) {
+  const tag = html.match(/<meta\b[^>]*name=["']viewport["'][^>]*>/i)?.[0];
+  if (!tag) {
+    return html.replace(
+      /<head[^>]*>/i,
+      (head) => `${head}\n    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />`,
+    );
+  }
+  if (/viewport-fit/i.test(tag)) return html;
+  return html.replace(
+    tag,
+    tag.replace(/content=(["'])((?:(?!\1).)*)\1/i, (_, q, c) => `content=${q}${c}, viewport-fit=cover${q}`),
+  );
+}
+
+// Cordova's default CSP blocks the inline import map ('unsafe-inline') and
+// Thread's blob: workers (worker-src falls back to script-src).
+function allowJopsScripts(html) {
+  const re = /(<meta\b[^>]*http-equiv=["']Content-Security-Policy["'][^>]*content=)(["'])((?:(?!\2).)*)\2/i;
+  const m = html.match(re);
+  if (!m) return html; // no CSP → nothing to relax
+  const directives = m[3].split(";").map((d) => d.trim()).filter(Boolean);
+  const i = directives.findIndex((d) => /^script-src\b/.test(d));
+  const required = ["'unsafe-inline'", "blob:"];
+  if (i >= 0) {
+    const missing = required.filter((src) => !directives[i].split(/\s+/).includes(src));
+    if (!missing.length) return html;
+    directives[i] += " " + missing.join(" ");
+  } else {
+    // No script-src: scripts fall back to default-src, so copy it and add what JOPS needs.
+    const def = directives.find((d) => /^default-src\b/.test(d))?.replace(/^default-src\s*/, "") ?? "'self'";
+    const sources = def.split(/\s+/).filter(Boolean);
+    directives.push(`script-src ${[...sources, ...required.filter((src) => !sources.includes(src))].join(" ")}`);
+  }
+  return html.replace(m[0], `${m[1]}${m[2]}${directives.join("; ")};${m[2]}`);
+}
+
+// cordova.js must be present; module scripts run after classic scripts, so order is safe.
+function ensureCordovaJs(html) {
+  if (/src=["'](\.\/)?cordova\.js["']/i.test(html)) return html;
+  return html.replace(/(\s*<script[^>]+jops-core\.min\.js)/i, `\n  <script src="cordova.js"></script>$1`);
+}
+
+// ─── config.xml helpers (Cordova) ────────────────────────────────────────────
+
+const IOS_SCHEME_PREFS = [["scheme", "app"], ["hostname", "localhost"]];
+
+// Preferences that apply to iOS: global ones plus those inside <platform name="ios">.
+function iosPrefScope(xml) {
+  return xml
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<platform\s+name=["'](?!ios["'])[^"']*["'][\s\S]*?<\/platform>/gi, "");
+}
+
+function prefValue(scope, name) {
+  const tag = scope.match(new RegExp(`<preference\\b[^>]*\\bname=["']${name}["'][^>]*>`, "i"))?.[0];
+  return tag ? (tag.match(/\bvalue=["']([^"']*)["']/i)?.[1] ?? "") : undefined;
+}
+
+// Cordova iOS serves from file:// unless a custom scheme is set; JOPS needs a real origin
+// for import() and fetch(). Existing values are never changed.
+function ensureIosScheme(xml) {
+  const scope = iosPrefScope(xml);
+  const missing = IOS_SCHEME_PREFS.filter(([name]) => prefValue(scope, name) === undefined);
+  if (!missing.length) return { xml, added: [] };
+
+  const lines = missing.map(([n, v]) => `        <preference name="${n}" value="${v}" />`).join("\n");
+  const iosOpen = /<platform\s+name=["']ios["']\s*>/i;
+  xml = iosOpen.test(xml)
+    ? xml.replace(iosOpen, (m) => `${m}\n${lines}`)
+    : xml.replace(/\s*<\/widget>\s*$/i, `\n    <platform name="ios">\n${lines}\n    </platform>\n</widget>\n`);
+  return { xml, added: missing.map(([n]) => n) };
+}
+
+function schemeWarnings(xml) {
+  const warnings = [];
+  const scheme = prefValue(iosPrefScope(xml), "scheme");
+  if (scheme !== undefined && /^(file|https?)?$/i.test(scheme)) {
+    warnings.push(`iOS preference scheme="${scheme}" keeps the app on file:// or is not allowed by WKWebView — JOPS needs a custom scheme such as "app".`);
+  }
+  const insecure = prefValue(xml.replace(/<!--[\s\S]*?-->/g, ""), "AndroidInsecureFileModeEnabled");
+  if (insecure?.toLowerCase() === "true") {
+    warnings.push("AndroidInsecureFileModeEnabled=true serves Android from file://, where JOPS cannot load modules.");
+  }
+  return warnings;
+}
+
 // ─── init ────────────────────────────────────────────────────────────────────
 
 if (command === "init") {
-  const indexPath = path.join(consumerRoot, "index.html");
-  const libDir = path.join(consumerRoot, "lib");
+  fs.mkdirSync(webRoot, { recursive: true });
+  if (isHybrid) {
+    console.log(`[jops-core] ${forced ? "Using" : "Detected"} ${type} project → web folder: ${rel(webRoot)}/`);
+  }
+
+  const indexPath = path.join(webRoot, "index.html");
+  const libDir = path.join(webRoot, "lib");
   const vendorDest = path.join(libDir, "jops-core.min.js");
   const vendorSrc = path.join(__dirname, "../lib/jops-core.min.js");
 
   if (!fs.existsSync(libDir)) fs.mkdirSync(libDir);
   fs.copyFileSync(vendorSrc, vendorDest);
-  console.log("[jops-core] Vendored jops-core.min.js → lib/jops-core.min.js");
+  console.log(`[jops-core] Vendored jops-core.min.js → ${rel(vendorDest)}`);
 
   const IMPORTMAP = `  <script type="importmap">
     {
@@ -57,16 +212,25 @@ if (command === "init") {
 
   const MODULE_SCRIPT = `  <script type="module" src="/lib/jops-core.min.js"></script>`;
 
+  const viewport = isHybrid
+    ? "width=device-width, initial-scale=1.0, viewport-fit=cover"
+    : "width=device-width, initial-scale=1.0";
+  const cordovaHead = type === "cordova"
+    ? `    <meta http-equiv="Content-Security-Policy" content="${CORDOVA_CSP}" />\n` +
+      `    <meta name="format-detection" content="telephone=no" />\n`
+    : "";
+  const cordovaBody = type === "cordova" ? `  <script src="cordova.js"></script>\n` : "";
+
   const TEMPLATE = `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+${cordovaHead}    <meta name="viewport" content="${viewport}" />
     <title>JOPS App</title>
 ${IMPORTMAP}
   </head>
   <body>
-${MODULE_SCRIPT}
+${cordovaBody}${MODULE_SCRIPT}
   </body>
 </html>
 `;
@@ -76,31 +240,60 @@ ${MODULE_SCRIPT}
     console.log("[jops-core] Created index.html with importmap and module script.");
   } else {
     let html = fs.readFileSync(indexPath, "utf8");
-    let changed = false;
+    const original = html;
 
     const hasImportmap = /type=["']importmap["']/.test(html) && html.includes('"jops-core"');
     if (!hasImportmap) {
       html = html.replace("</head>", `${IMPORTMAP}\n  </head>`);
-      changed = true;
       console.log("[jops-core] Added importmap to index.html.");
     }
 
     const hasModuleScript = /src=["'][^"']*jops-core\.min\.js["']/.test(html);
     if (!hasModuleScript) {
       html = html.replace("</body>", `${MODULE_SCRIPT}\n  </body>`);
-      changed = true;
       console.log("[jops-core] Added module script to index.html.");
     }
 
-    if (changed) {
+    if (isHybrid) {
+      const before = html;
+      html = ensureViewportFitCover(html);
+      if (html !== before) console.log("[jops-core] Added viewport-fit=cover to index.html.");
+    }
+
+    if (type === "cordova") {
+      let before = html;
+      html = allowJopsScripts(html);
+      if (html !== before) console.log("[jops-core] Content-Security-Policy: allowed the inline importmap ('unsafe-inline') and Thread workers (blob:).");
+      before = html;
+      html = ensureCordovaJs(html);
+      if (html !== before) console.log("[jops-core] Added cordova.js to index.html.");
+    }
+
+    if (html !== original) {
       fs.writeFileSync(indexPath, html, "utf8");
     } else {
       console.log("[jops-core] index.html already configured.");
     }
   }
 
-  // VS Code extension recommendation
-  const vscodeSettingsDir = path.join(consumerRoot, ".vscode");
+  if (type === "cordova") {
+    const configPath = path.join(projectRoot, "config.xml");
+    if (fs.existsSync(configPath)) {
+      const { xml, added } = ensureIosScheme(fs.readFileSync(configPath, "utf8"));
+      if (added.length) {
+        fs.writeFileSync(configPath, xml, "utf8");
+        const list = IOS_SCHEME_PREFS.filter(([n]) => added.includes(n)).map(([n, v]) => `${n}="${v}"`).join(", ");
+        console.log(`[jops-core] config.xml: added iOS preference ${list} — applied on the next cordova prepare/build.`);
+        if (added.includes("scheme")) {
+          console.log("[jops-core] Note: if this app is already published, data stored under file:// (localStorage, IndexedDB) is not visible from the new origin.");
+        }
+      }
+      schemeWarnings(xml).forEach((w) => console.warn(`[jops-core] Warning: ${w}`));
+    }
+  }
+
+  // VS Code extension recommendation (project root, so it is never bundled into a hybrid app)
+  const vscodeSettingsDir = path.join(projectRoot, ".vscode");
   if (!fs.existsSync(vscodeSettingsDir)) fs.mkdirSync(vscodeSettingsDir);
 
   const extensionsJsonPath = path.join(vscodeSettingsDir, "extensions.json");
@@ -139,11 +332,12 @@ ${MODULE_SCRIPT}
   console.log("[jops-core] VS Code: install the recommended 'lit-html' extension (bierner.lit-html) for HTML highlighting inside layout`` template literals.");
 
   // Inject scripts into consumer's package.json
-  const pkgPath = path.join(consumerRoot, "package.json");
+  const pkgPath = path.join(projectRoot, "package.json");
   if (fs.existsSync(pkgPath)) {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
     let changed = false;
-    if (!pkg.scripts?.build) {
+    // Hybrid projects build with cordova/cap; `jops-core build` would copy the native platform folders.
+    if (!isHybrid && !pkg.scripts?.build) {
       pkg.scripts = { ...pkg.scripts, build: "npx jops-core build" };
       changed = true;
       console.log('[jops-core] Added "build" script to package.json.');
@@ -169,9 +363,20 @@ ${MODULE_SCRIPT}
   );
   rl.close();
 
+  // Cordova's sample page (css/index.css, js/index.js, #deviceready) conflicts with a JOPS
+  // template: back it up and start from the JOPS Cordova index.html instead.
+  if (type === "cordova" && ["1", "2"].includes(choice.trim()) &&
+      fs.readFileSync(indexPath, "utf8").includes('id="deviceready"')) {
+    let backup = path.join(webRoot, "index.cordova.html");
+    for (let n = 1; fs.existsSync(backup); n++) backup = path.join(webRoot, `index.cordova-${n}.html`);
+    fs.renameSync(indexPath, backup);
+    fs.writeFileSync(indexPath, TEMPLATE, "utf8");
+    console.log(`[jops-core] Replaced Cordova's sample index.html (backup: ${rel(backup)}). css/index.css and js/index.js are no longer used.`);
+  }
+
   const templateSrc = path.join(__dirname, "../templates");
   if (choice.trim() === "1") {
-    copyDir(path.join(templateSrc, "empty"), consumerRoot);
+    copyDir(path.join(templateSrc, "empty"), webRoot);
     // Add data-app to the module script in index.html
     let html = fs.readFileSync(indexPath, "utf8");
     html = html.replace(
@@ -181,7 +386,7 @@ ${MODULE_SCRIPT}
     fs.writeFileSync(indexPath, html, "utf8");
     console.log("[jops-core] Created empty JOPS project skeleton.");
   } else if (choice.trim() === "2") {
-    copyDir(path.join(templateSrc, "hello-world"), consumerRoot);
+    copyDir(path.join(templateSrc, "hello-world"), webRoot);
     let html = fs.readFileSync(indexPath, "utf8");
     html = html.replace(
       /(<script[^>]+src=["'][^"']*jops-core\.min\.js["'])([^>]*>)/,
@@ -197,24 +402,30 @@ ${MODULE_SCRIPT}
 // ─── update ──────────────────────────────────────────────────────────────────
 
 if (command === "update") {
-  const libDir = path.join(consumerRoot, "lib");
+  const libDir = path.join(webRoot, "lib");
   const vendorDest = path.join(libDir, "jops-core.min.js");
   const vendorSrc = path.join(__dirname, "../lib/jops-core.min.js");
 
   if (!fs.existsSync(libDir)) {
-    console.error("[jops-core] lib/ folder not found. Run 'npx jops-core init' first.");
+    console.error(`[jops-core] ${rel(libDir)}/ folder not found. Run 'npx jops-core init' first.`);
     process.exit(1);
   }
 
   fs.copyFileSync(vendorSrc, vendorDest);
 
   const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "../package.json"), "utf8"));
-  console.log(`[jops-core] Updated lib/jops-core.min.js to v${pkg.version}`);
+  console.log(`[jops-core] Updated ${rel(vendorDest)} to v${pkg.version}`);
 }
 
 // ─── build ───────────────────────────────────────────────────────────────────
 
 if (command === "build") {
+  if (isHybrid) {
+    const native = type === "cordova" ? "cordova build" : "npx cap sync";
+    console.log(`[jops-core] Not needed in a ${type} project — ${rel(webRoot)}/ is shipped as-is. Use \`${native}\`.`);
+    process.exit(0);
+  }
+
   const BUILD_EXCLUDE = new Set([
     "node_modules", "dist", ".git",
     "package.json", "package-lock.json", ".gitignore", ".npmrc",
@@ -235,8 +446,8 @@ if (command === "build") {
     }
   }
 
-  const distDir = path.join(consumerRoot, "dist");
+  const distDir = path.join(webRoot, "dist");
   if (fs.existsSync(distDir)) fs.rmSync(distDir, { recursive: true, force: true });
-  buildCopyDir(consumerRoot, distDir);
+  buildCopyDir(webRoot, distDir);
   console.log("[jops-core] Built → dist/");
 }

package/lib/jops-core.d.ts

@@ -72,9 +72,12 @@ export declare class View {
      */
     constructor(layout?: string);
     /**
-     * Override to load a layout `.js` module or set `this.layout` inline.
+     * Override to load a layout file or set `this.layout` inline.
      * Called automatically by the framework before `inflate()`.
-     * @param {string} [layout] - Path to a `.js` layout module or an inline HTML string.
+     * @param {string} [layout] - Path to a `.js` layout module, a `.html` file, or an inline HTML string.
+     *   `.js` — dynamically imported as an ES module; must export a `layout\`...\`` string as default.
+     *   `.html` — fetched and cached for the page lifetime; plain HTML fragment, no import/export needed.
+     *   Any other value — treated as an inline HTML string assigned directly to `this.layout`.
      * @returns {Promise<void>}
      */
     loadLayout(layout?: string): Promise<void>;
@@ -241,7 +244,7 @@ export declare class Router extends View {
     routes: {};
     _navStack: any[];
     _baseView: any;
-    _pendingBack: boolean;
+    _idx: any;
     _currentView: any;
     /**
      * Returns the single Router instance after it has been rendered.
@@ -251,6 +254,14 @@ export declare class Router extends View {
     constructor(routerDomNode: any);
     onLayout(): Promise<void>;
     initRouter(): void;
+    /**
+     * Single entry point for popstate and hashchange. Decides the direction
+     * from the history entry's position and dispatches to _onBack/_onForward.
+     */
+    _onHistoryChange(): void;
+    _onBack(): void;
+    _onForward(): void;
+    _switchToHash(): void;
     _animateTransition(outgoing: any, incoming: any, direction: any): Promise<void>;
     _slideTransition(outgoing: any, incoming: any, direction: any): Promise<void>;
     _fadeTransition(outgoing: any, incoming: any): Promise<void>;
@@ -260,6 +271,12 @@ export declare class Router extends View {
      * otherwise calls `history.back()`.
      */
     back(): void;
+    /**
+     * Returns true if there is an earlier JOPS history entry to go back to.
+     * Equivalent to checking the back stack before calling `onBackPressed()` in Android.
+     * @returns {boolean}
+     */
+    canGoBack(): boolean;
     /**
      * Returns the current URL query params as a plain object.
      * Works for both flat (`href="#path?k=v"`) and stack (`navigate("/path?k=v")`) routes.

package/lib/jops-core.min.js

@@ -1 +1 @@
-var k=Object.defineProperty;var c=(i,t)=>k(i,"name",{value:t,configurable:!0});var _=new URL(import.meta.url).origin!==location.origin,p=new Map;function f(i){if(!i)return i;if(_){if(i.startsWith("/"))return"."+i}else if(i.startsWith("./"))return i.slice(1);return i}c(f,"normalizePath");(()=>{console.log("JOPS initialized");let i=document.querySelector("script[data-app]")?.dataset.app??"./src/App.js";import(new URL(f(i),document.baseURI).href).then(t=>new t.default).catch(t=>console.error("JOPS: App.js not found or failed to load",t))})();var m=class{static{c(this,"RawHTML")}constructor(t){this.html=t}},E=c(i=>new m(i),"raw");function v(i,...t){return i.reduce((e,s,n)=>{if(n>=t.length)return e+s;let o=t[n];return o==null?e+s:o instanceof m?e+s+o.html:e+s+String(o).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")},"")}c(v,"layout");var w=class{static{c(this,"Element")}constructor(t,e){this.element=t?.id===e?t:t.querySelector(`#${e}`)}set(t){this.element.innerHTML=t}value(){return this.element.innerHTML}},y=class i{static{c(this,"View")}#t=!1;#e=!1;constructor(t){this.loadLayout(t),this.subViews=[]}async loadLayout(t){if(t)if(t.endsWith(".js"))try{let e=await import(new URL(f(t),document.baseURI).href);this.layout=e.default}catch(e){console.error("JOPS: failed to load layout:",t,e)}else if(t.endsWith(".html")||t.endsWith(".htm"))try{let e=new URL(f(t),document.baseURI).href;if(p.has(e))this.layout=p.get(e);else{let s=await fetch(e);if(!s.ok)throw new Error(`HTTP ${s.status}`);let n=await s.text();p.set(e,n),this.layout=n}}catch(e){console.error("JOPS: failed to load layout:",t,e)}else this.layout=t}setStyle(t){if(t)if(this.style=t,t.endsWith(".css")){if(document.querySelector(`link[href="${t}"]`))return;let e=document.createElement("link");e.rel="stylesheet",e.href=t,document.head.appendChild(e)}else{if(document.querySelector(`style[data-jops="${t}"]`))return;let e=document.createElement("style");e.setAttribute("data-jops",t),e.textContent=t,document.head.appendChild(e)}}get(t){return new w(this.domNode,t)}bindEvents(){if(!this.domNode)return;let t=[...this.domNode.querySelectorAll("[jops-event-bind], [type='jops-event-bind']")];(this.domNode.hasAttribute("jops-event-bind")||this.domNode.getAttribute("type")==="jops-event-bind")&&t.unshift(this.domNode);for(let e of t)for(let s of e.attributes){if(!s.name.startsWith("on"))continue;let n=s.value.trim();typeof this[n]=="function"&&(e[s.name]=o=>this[n](o))}}inflate(){if(!this.layout||this.#t)return;this.#t=!0;let t=document.createElement("template");t.innerHTML=this.layout;let s=t.content.cloneNode(!0).firstElementChild;this.domNode=s}async addSubView(t,e){this.subViews.push(e),e.domNode||(await e.loadLayout(),e.inflate()),this.domNode.querySelector(`#${t}`).appendChild(e.domNode),await e?.onLayout?.(),await e?.onResume?.(),e?.bindEvents?.()}hide(){this.domNode.style.display="none"}show(){this.domNode.style.display=""}find(t){let e=[];for(let s of this.subViews)t(s)&&e.push(s),e.push(...s.find?.(t)??[]);return e}destroy(){this.subViews.forEach(t=>t.destroy?.()),this.subViews=[],this.domNode?.remove(),this.domNode=null,this.layout=null}removeSubView(t){t.destroy?.(),this.subViews=this.subViews.filter(e=>e!==t)}async insertSubView(t,e){t.domNode||(await t.loadLayout(),t.inflate());let s=this.domNode.children[e]??null;this.domNode.insertBefore(t.domNode,s),this.subViews.splice(e,0,t),await t?.onLayout?.(),await t?.onResume?.(),t?.bindEvents?.()}async render(){if(!this.layout||this.#e)return;this.#e=!0;let t=this.domNode??document.body;t===document.body&&(t.innerHTML=this.layout);let e=Array.from(t.querySelectorAll("[jops], [type='jops']")).filter(s=>s.tagName==="ROUTER"||!s.closest("router")||s.closest("router")===t);e.length!==0&&await Promise.all(e.map(async s=>{if(s.tagName==="ROUTER"){let l=new b(s);await l.render(),await l.onLayout();return}let n=s.getAttribute("layout"),o=s.getAttribute("src");if(!o&&!n)return;let r;if(o){let h=(await import(new URL(f(o),document.baseURI).href)).default;r=new h}else r=new i;this.subViews.push(r),await r.loadLayout(n);let a=document.createElement("template");a.innerHTML=r.layout??"";let d=a.content.cloneNode(!0);if(s.children.length>0){let l=d.firstElementChild??d;Array.from(s.children).forEach(h=>l.appendChild(h))}let u=d.firstElementChild;r.routePath=s.getAttribute("path"),s.replaceWith(d),r.domNode=u,await r.render(),await r?.onLayout?.(),await r?.onResume?.(),r?.bindEvents?.()}))}},R=class i{static{c(this,"EventBus")}static#t={};static subscribe(t,e){i.#t[t]||(i.#t[t]=[]),i.#t[t].push(e)}static send(t,e){i.#t[t]?.forEach(s=>s(e))}static unsubscribe(t,e){i.#t[t]&&(i.#t[t]=i.#t[t].filter(s=>s!==e))}},S=class i{static{c(this,"Store")}static#t=null;static singleton(){return i.#t||(i.#t=new i),i.#t}constructor(){this._state={}}get(t){return t.split(".").reduce((e,s)=>e?.[s],this._state)}set(t,e){let s=t.split("."),n=s.pop(),o=s.reduce((r,a)=>(r[a]||(r[a]={}),r[a]),this._state);o[n]=e}clear(){this._state={}}},b=class i extends y{static{c(this,"Router")}static#t=null;static singleton(){return i.#t}constructor(t){super(),i.#t=this,this.rootNode=t.parentNode,this.routerDomNode=t,this.domNode=t,this.layout=t.innerHTML,this.animation=t.getAttribute("animation")??"none"}async onLayout(){let t=document.createDocumentFragment();for(;this.routerDomNode.firstChild;)t.appendChild(this.routerDomNode.firstChild);this.routerDomNode.replaceWith(t),this.domNode=this.rootNode,this.initRouter()}initRouter(){this.routes={};for(let o of this.subViews)if(o.routePath){let r=o.routePath.slice(1).split("?")[0];this.routes[r]=o}this._navStack=[],this._baseView=null;for(let o of Object.values(this.routes))o.domNode.hidden=!0;let t=Object.keys(this.routes)[0],e=window.location.hash.slice(1),s=e.split("?")[0],n=s&&this.routes[s]?e:t;history.replaceState(null,"","#"+n),window.addEventListener("hashchange",()=>{let o=window.location.hash.slice(1),r=o.split("?")[0];if(!(!r||!this.routes[r])){if(this._pendingBack){this._pendingBack=!1;return}this._switchTo(o)}}),window.addEventListener("popstate",()=>{if(this._navStack.length>0){let a=this._navStack.pop(),d=this._navStack.at(-1)??this._baseView;a?.onBackPressed?.(),this._animateTransition(a,d,"back").then(()=>a.destroy());return}this._currentView?.onBackPressed?.();let o=window.location.hash.slice(1),r=o.split("?")[0];r&&this.routes[r]&&(this._pendingBack=!0,this._switchTo(o))}),this._switchTo(n)}async _animateTransition(t,e,s){this.animation==="slide"?await this._slideTransition(t,e,s):this.animation==="fade"?await this._fadeTransition(t,e):(t.domNode.hidden=!0,e.domNode.hidden=!1,this._currentView=e,e?.onResume?.())}async _slideTransition(t,e,s){let n=this.domNode,o=s==="forward",r=n.getBoundingClientRect(),a=t.domNode.getBoundingClientRect(),d=a.left-r.left,u=a.top-r.top,l=a.width,h=n.offsetWidth-d,N=`position:absolute;left:${d}px;top:${u}px;width:${l}px`;n.style.cssText=`position:relative;overflow:hidden;height:${n.offsetHeight}px`,t.domNode.style.cssText=`${N};z-index:${o?1:2}`,t.domNode.hidden=!1,e.domNode.style.cssText=`${N};z-index:${o?2:1}`,e.domNode.hidden=!1;let L=o?e.domNode:t.domNode,g=o?`${h}px`:"0px",V=o?"0px":`${h}px`,T=L.animate([{transform:`translateX(${g})`},{transform:`translateX(${V})`}],{duration:300,easing:"ease",fill:"forwards"});await T.finished,T.cancel(),t.domNode.hidden=!0,t.domNode.style.cssText="",e.domNode.style.cssText="",n.style.cssText="",this._currentView=e,e?.onResume?.()}async _fadeTransition(t,e){let s=this.domNode,n=s.getBoundingClientRect(),o=t.domNode.getBoundingClientRect(),r=o.left-n.left,a=o.top-n.top,d=o.width,u=`position:absolute;left:${r}px;top:${a}px;width:${d}px`;s.style.cssText=`position:relative;overflow:hidden;height:${s.offsetHeight}px`,t.domNode.style.cssText=u,t.domNode.hidden=!1,e.domNode.style.cssText=u,e.domNode.hidden=!1;let l=t.domNode.animate([{opacity:1},{opacity:0}],{duration:450,easing:"ease",fill:"forwards"}),h=e.domNode.animate([{opacity:0},{opacity:1}],{duration:450,easing:"ease",fill:"forwards"});await Promise.all([l.finished,h.finished]),l.cancel(),h.cancel(),t.domNode.hidden=!0,t.domNode.style.cssText="",e.domNode.style.cssText="",s.style.cssText="",this._currentView=e,e?.onResume?.()}_switchTo(t){let e=t.split("?")[0];for(let[s,n]of Object.entries(this.routes)){let o=s===e;n.domNode.hidden=!o,o&&(this._currentView=n,n?.onResume?.())}}back(){history.back()}getParams(){let t=window.location.hash.split("?")[1];return t?Object.fromEntries(new URLSearchParams(t)):{}}async navigate(t,e){let[s,n]=t.replace(/^\//,"").split("?"),o=s,r=e??this.routes[o]?.constructor;if(!r){console.error(`JOPS Router: no class found for path "${t}"`);return}this._navStack.length===0&&(this._baseView=this._currentView);let a=new r;await a.loadLayout(),a.inflate(),this.domNode.appendChild(a.domNode),history.pushState({jopsNav:!0},"","#"+o+(n?"?"+n:"")),await a.onLayout?.(),await a.onResume?.(),a.bindEvents?.(),this._navStack.push(a),this._animateTransition(this._currentView,a,"forward")}async replace(t,e){this._navStack.forEach(a=>a.destroy?.()),this._navStack=[];let[s,n]=t.replace(/^\//,"").split("?"),o=s,r="#"+o+(n?"?"+n:"");if(this.routes[o])history.replaceState(null,"",r),this._switchTo(o);else if(e){let a=new e;await a.loadLayout(),a.inflate(),this.domNode.appendChild(a.domNode),await a.onLayout?.(),await a.onResume?.(),a.bindEvents?.(),this._currentView&&(this._currentView.domNode.hidden=!0),this._currentView=a,history.replaceState(null,"",r)}else console.error(`JOPS Router: no instance or class found for path "${t}"`)}},x=class{static{c(this,"Thread")}#t=null;run(t){}onMessage(t){}start(t){if(typeof Worker>"u"){console.warn("JOPS Thread: Web Workers are not supported in this environment.");return}let e=this.run.toString();!e.startsWith("function")&&!e.startsWith("(")&&!e.startsWith("async")&&(e="function "+e);let s=new Blob([`const run = ${e};`,"self.onmessage = (e) => { run(e.data); };"],{type:"application/javascript"}),n=URL.createObjectURL(s);this.#t=new Worker(n),URL.revokeObjectURL(n),this.#t.onmessage=o=>this.onMessage(o),this.#t.postMessage(t)}terminate(){if(!this.#t){console.warn("JOPS Thread: no active worker to terminate.");return}this.#t.terminate(),this.#t=null}};export{R as EventBus,b as Router,S as Store,x as Thread,y as View,v as layout,E as raw};
+var R=Object.defineProperty;var d=(o,t)=>R(o,"name",{value:t,configurable:!0});var v=new URL(import.meta.url).origin!==location.origin,w=new Map;function f(o){if(!o)return o;if(v){if(o.startsWith("/"))return"."+o}else if(o.startsWith("./"))return o.slice(1);return o}d(f,"normalizePath");(()=>{console.log("JOPS initialized");let o=document.querySelector("script[data-app]"),t=o?.dataset.app??"./src/App.js";import(new URL(f(t),document.baseURI).href).then(e=>new e.default).catch(e=>console.error("JOPS: App.js not found or failed to load",e)),o?.dataset.nativeBack!=="off"&&V()})();function V(){document.addEventListener("deviceready",()=>{let o=window.Capacitor;o?.isNativePlatform?.()&&o.getPlatform()==="android"&&!o.isPluginAvailable("App")&&console.warn("JOPS: install @capacitor/app so the Android back button navigates instead of closing the app.");let t=0;document.addEventListener("backbutton",()=>{let e=Date.now();if(e-t<300)return;t=e;let s=m.singleton();s?.canGoBack()?s.back():!s&&window.navigation?.canGoBack?history.back():navigator.app.exitApp()})},{once:!0})}d(V,"installNativeBackButton");var p=class{static{d(this,"RawHTML")}constructor(t){this.html=t}},E=d(o=>new p(o),"raw");function P(o,...t){return o.reduce((e,s,i)=>{if(i>=t.length)return e+s;let n=t[i];return n==null?e+s:n instanceof p?e+s+n.html:e+s+String(n).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")},"")}d(P,"layout");var y=class{static{d(this,"Element")}constructor(t,e){this.element=t?.id===e?t:t.querySelector(`#${e}`)}set(t){this.element.innerHTML=t}value(){return this.element.innerHTML}},b=class o{static{d(this,"View")}#t=!1;#e=!1;constructor(t){this.loadLayout(t),this.subViews=[]}async loadLayout(t){if(t)if(t.endsWith(".js"))try{let e=await import(new URL(f(t),document.baseURI).href);this.layout=e.default}catch(e){console.error("JOPS: failed to load layout:",t,e)}else if(t.endsWith(".html")||t.endsWith(".htm"))try{let e=new URL(f(t),document.baseURI).href;if(w.has(e))this.layout=w.get(e);else{let s=await fetch(e);if(!s.ok)throw new Error(`HTTP ${s.status}`);let i=await s.text();w.set(e,i),this.layout=i}}catch(e){console.error("JOPS: failed to load layout:",t,e)}else this.layout=t}setStyle(t){if(t)if(this.style=t,t.endsWith(".css")){if(document.querySelector(`link[href="${t}"]`))return;let e=document.createElement("link");e.rel="stylesheet",e.href=t,document.head.appendChild(e)}else{if(document.querySelector(`style[data-jops="${t}"]`))return;let e=document.createElement("style");e.setAttribute("data-jops",t),e.textContent=t,document.head.appendChild(e)}}get(t){return new y(this.domNode,t)}bindEvents(){if(!this.domNode)return;let t=[...this.domNode.querySelectorAll("[jops-event-bind], [type='jops-event-bind']")];(this.domNode.hasAttribute("jops-event-bind")||this.domNode.getAttribute("type")==="jops-event-bind")&&t.unshift(this.domNode);for(let e of t)for(let s of e.attributes){if(!s.name.startsWith("on"))continue;let i=s.value.trim();typeof this[i]=="function"&&(e[s.name]=n=>this[i](n))}}inflate(){if(!this.layout||this.#t)return;this.#t=!0;let t=document.createElement("template");t.innerHTML=this.layout;let s=t.content.cloneNode(!0).firstElementChild;this.domNode=s}async addSubView(t,e){this.subViews.push(e),e.domNode||(await e.loadLayout(),e.inflate()),this.domNode.querySelector(`#${t}`).appendChild(e.domNode),await e?.onLayout?.(),await e?.onResume?.(),e?.bindEvents?.()}hide(){this.domNode.style.display="none"}show(){this.domNode.style.display=""}find(t){let e=[];for(let s of this.subViews)t(s)&&e.push(s),e.push(...s.find?.(t)??[]);return e}destroy(){this.subViews.forEach(t=>t.destroy?.()),this.subViews=[],this.domNode?.remove(),this.domNode=null,this.layout=null}removeSubView(t){t.destroy?.(),this.subViews=this.subViews.filter(e=>e!==t)}async insertSubView(t,e){t.domNode||(await t.loadLayout(),t.inflate());let s=this.domNode.children[e]??null;this.domNode.insertBefore(t.domNode,s),this.subViews.splice(e,0,t),await t?.onLayout?.(),await t?.onResume?.(),t?.bindEvents?.()}async render(){if(!this.layout||this.#e)return;this.#e=!0;let t=this.domNode??document.body;t===document.body&&(t.innerHTML=this.layout);let e=Array.from(t.querySelectorAll("[jops], [type='jops']")).filter(s=>s.tagName==="ROUTER"||!s.closest("router")||s.closest("router")===t);e.length!==0&&await Promise.all(e.map(async s=>{if(s.tagName==="ROUTER"){let c=new m(s);await c.render(),await c.onLayout();return}let i=s.getAttribute("layout"),n=s.getAttribute("src");if(!n&&!i)return;let r;if(n){let l=(await import(new URL(f(n),document.baseURI).href)).default;r=new l}else r=new o;this.subViews.push(r),await r.loadLayout(i);let a=document.createElement("template");a.innerHTML=r.layout??"";let h=a.content.cloneNode(!0);if(s.children.length>0){let c=h.firstElementChild??h;Array.from(s.children).forEach(l=>c.appendChild(l))}let u=h.firstElementChild;r.routePath=s.getAttribute("path"),s.replaceWith(h),r.domNode=u,await r.render(),await r?.onLayout?.(),await r?.onResume?.(),r?.bindEvents?.()}))}},_=class o{static{d(this,"EventBus")}static#t={};static subscribe(t,e){o.#t[t]||(o.#t[t]=[]),o.#t[t].push(e)}static send(t,e){o.#t[t]?.forEach(s=>s(e))}static unsubscribe(t,e){o.#t[t]&&(o.#t[t]=o.#t[t].filter(s=>s!==e))}},S=class o{static{d(this,"Store")}static#t=null;static singleton(){return o.#t||(o.#t=new o),o.#t}constructor(){this._state={}}get(t){return t.split(".").reduce((e,s)=>e?.[s],this._state)}set(t,e){let s=t.split("."),i=s.pop(),n=s.reduce((r,a)=>(r[a]||(r[a]={}),r[a]),this._state);n[i]=e}clear(){this._state={}}},m=class o extends b{static{d(this,"Router")}static#t=null;static singleton(){return o.#t}constructor(t){super(),o.#t=this,this.rootNode=t.parentNode,this.routerDomNode=t,this.domNode=t,this.layout=t.innerHTML,this.animation=t.getAttribute("animation")??"none"}async onLayout(){let t=document.createDocumentFragment();for(;this.routerDomNode.firstChild;)t.appendChild(this.routerDomNode.firstChild);this.routerDomNode.replaceWith(t),this.domNode=this.rootNode,this.initRouter()}initRouter(){this.routes={};for(let r of this.subViews)if(r.routePath){let a=r.routePath.slice(1).split("?")[0];this.routes[a]=r}this._navStack=[],this._baseView=null;for(let r of Object.values(this.routes))r.domNode.hidden=!0;let t=Object.keys(this.routes)[0],e=window.location.hash.slice(1),s=e.split("?")[0],i=s&&this.routes[s]?e:t;this._idx=history.state?.jopsIdx??0,history.replaceState({...history.state,jopsIdx:this._idx},"","#"+i);let n=d(()=>this._onHistoryChange(),"onHistoryChange");window.addEventListener("popstate",n),window.addEventListener("hashchange",n),this._switchTo(i)}_onHistoryChange(){let t=history.state?.jopsIdx;if(t===this._idx)return;if(t===void 0){this._idx+=1,history.replaceState({...history.state,jopsIdx:this._idx},"",location.href),this._onForward();return}let e=t<this._idx;this._idx=t,e?this._onBack():this._onForward()}_onBack(){if(this._navStack.length>0){let e=this._navStack.pop(),s=this._navStack.at(-1)??this._baseView;e?.onBackPressed?.(),this._animateTransition(e,s,"back").then(()=>e.destroy());return}let t=window.location.hash.slice(1).split("?")[0];if(!this.routes[t]){history.back();return}this._currentView?.onBackPressed?.(),this._switchToHash()}_onForward(){this._navStack.length>0&&(this._navStack.forEach(t=>t.destroy?.()),this._navStack=[],this._baseView=null),this._switchToHash()}_switchToHash(){let t=window.location.hash.slice(1),e=t.split("?")[0];e&&this.routes[e]&&this._switchTo(t)}async _animateTransition(t,e,s){this.animation==="slide"?await this._slideTransition(t,e,s):this.animation==="fade"?await this._fadeTransition(t,e):(t.domNode.hidden=!0,e.domNode.hidden=!1,this._currentView=e,e?.onResume?.())}async _slideTransition(t,e,s){let i=this.domNode,n=s==="forward",r=i.getBoundingClientRect(),a=t.domNode.getBoundingClientRect(),h=a.left-r.left,u=a.top-r.top,c=a.width,l=i.offsetWidth-h,N=`position:absolute;left:${h}px;top:${u}px;width:${c}px`;i.style.cssText=`position:relative;overflow:hidden;height:${i.offsetHeight}px`,t.domNode.style.cssText=`${N};z-index:${n?1:2}`,t.domNode.hidden=!1,e.domNode.style.cssText=`${N};z-index:${n?2:1}`,e.domNode.hidden=!1;let T=n?e.domNode:t.domNode,g=n?`${l}px`:"0px",L=n?"0px":`${l}px`,x=T.animate([{transform:`translateX(${g})`},{transform:`translateX(${L})`}],{duration:300,easing:"ease",fill:"forwards"});await x.finished,x.cancel(),t.domNode.hidden=!0,t.domNode.style.cssText="",e.domNode.style.cssText="",i.style.cssText="",this._currentView=e,e?.onResume?.()}async _fadeTransition(t,e){let s=this.domNode,i=s.getBoundingClientRect(),n=t.domNode.getBoundingClientRect(),r=n.left-i.left,a=n.top-i.top,h=n.width,u=`position:absolute;left:${r}px;top:${a}px;width:${h}px`;s.style.cssText=`position:relative;overflow:hidden;height:${s.offsetHeight}px`,t.domNode.style.cssText=u,t.domNode.hidden=!1,e.domNode.style.cssText=u,e.domNode.hidden=!1;let c=t.domNode.animate([{opacity:1},{opacity:0}],{duration:450,easing:"ease",fill:"forwards"}),l=e.domNode.animate([{opacity:0},{opacity:1}],{duration:450,easing:"ease",fill:"forwards"});await Promise.all([c.finished,l.finished]),c.cancel(),l.cancel(),t.domNode.hidden=!0,t.domNode.style.cssText="",e.domNode.style.cssText="",s.style.cssText="",this._currentView=e,e?.onResume?.()}_switchTo(t){let e=t.split("?")[0];for(let[s,i]of Object.entries(this.routes)){let n=s===e;i.domNode.hidden=!n,n&&(this._currentView=i,i?.onResume?.())}}back(){history.back()}canGoBack(){return this._idx>0}getParams(){let t=window.location.hash.split("?")[1];return t?Object.fromEntries(new URLSearchParams(t)):{}}async navigate(t,e){let[s,i]=t.replace(/^\//,"").split("?"),n=s,r=e??this.routes[n]?.constructor;if(!r){console.error(`JOPS Router: no class found for path "${t}"`);return}this._navStack.length===0&&(this._baseView=this._currentView);let a=new r;await a.loadLayout(),a.inflate(),this.domNode.appendChild(a.domNode),history.pushState({jopsNav:!0,jopsIdx:++this._idx},"","#"+n+(i?"?"+i:"")),await a.onLayout?.(),await a.onResume?.(),a.bindEvents?.(),this._navStack.push(a),this._animateTransition(this._currentView,a,"forward")}async replace(t,e){this._navStack.forEach(a=>a.destroy?.()),this._navStack=[];let[s,i]=t.replace(/^\//,"").split("?"),n=s,r="#"+n+(i?"?"+i:"");if(this.routes[n])history.replaceState({jopsIdx:this._idx},"",r),this._switchTo(n);else if(e){let a=new e;await a.loadLayout(),a.inflate(),this.domNode.appendChild(a.domNode),await a.onLayout?.(),await a.onResume?.(),a.bindEvents?.(),this._currentView&&(this._currentView.domNode.hidden=!0),this._currentView=a,history.replaceState({jopsIdx:this._idx},"",r)}else console.error(`JOPS Router: no instance or class found for path "${t}"`)}},k=class{static{d(this,"Thread")}#t=null;run(t){}onMessage(t){}start(t){if(typeof Worker>"u"){console.warn("JOPS Thread: Web Workers are not supported in this environment.");return}let e=this.run.toString();!e.startsWith("function")&&!e.startsWith("(")&&!e.startsWith("async")&&(e="function "+e);let s=new Blob([`const run = ${e};`,"self.onmessage = (e) => { run(e.data); };"],{type:"application/javascript"}),i=URL.createObjectURL(s);this.#t=new Worker(i),URL.revokeObjectURL(i),this.#t.onmessage=n=>this.onMessage(n),this.#t.postMessage(t)}terminate(){if(!this.#t){console.warn("JOPS Thread: no active worker to terminate.");return}this.#t.terminate(),this.#t=null}};export{_ as EventBus,m as Router,S as Store,k as Thread,b as View,P as layout,E as raw};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jops-core",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "A no-bundler, OOP-first SPA framework with Android-style view composition",
   "type": "module",
   "exports": "./lib/jops-core.min.js",

package/templates/hello-world/src/css/styles.css

@@ -54,7 +54,11 @@ body {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  padding: var(--spacing-md) var(--spacing-lg);
+  /* safe-area insets are 0 unless the page uses viewport-fit=cover (Cordova/Capacitor) */
+  padding: calc(var(--spacing-md) + env(safe-area-inset-top, 0px))
+    calc(var(--spacing-lg) + env(safe-area-inset-right, 0px))
+    var(--spacing-md)
+    calc(var(--spacing-lg) + env(safe-area-inset-left, 0px));
   background: var(--color-surface);
   border-bottom: 1px solid var(--color-border);
   box-shadow: var(--shadow-sm);
@@ -452,7 +456,8 @@ body {
 /* ── Footer ──────────────────────────────────────────────────── */
 .footer {
   text-align: center;
-  padding: var(--spacing-lg);
+  padding: var(--spacing-lg) var(--spacing-lg)
+    calc(var(--spacing-lg) + env(safe-area-inset-bottom, 0px));
   background: var(--color-surface);
   border-top: 1px solid var(--color-border);
   display: flex;