jops-core 1.0.15 → 1.1.1

package/bin/init.js

@@ -3,14 +3,15 @@ import fs from "fs";
 import https from "https";
 import path from "path";
 import readline from "readline";
+import { spawnSync } from "child_process";
 import { fileURLToPath } from "url";
 
 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 init    — vendor library and configure index.html, or create a template project");
+  console.log("  npx jops-core update  — copy the latest jops-core.min.js to lib/ (public/lib/ in a Next.js project)");
   console.log("  npx jops-core build   — generate production-ready dist/ folder");
   console.log("");
   console.log("Options (init, update):");
@@ -143,6 +144,133 @@ function copyDir(src, dest) {
   }
 }
 
+// A Next.js project: the library is served from public/lib/.
+function isNextProject(dir) {
+  return ["next.config.ts", "next.config.js", "next.config.mjs"].some((f) => fs.existsSync(path.join(dir, f)));
+}
+
+// Copies a template project into dest (README.md included, unlike copyDir()).
+// package.json is merged separately; existing files are never overwritten.
+// npm drops .gitignore files from published packages, so the template stores
+// it as "gitignore".
+function copyTemplateProject(src, dest, root = dest) {
+  const SKIP = new Set(["node_modules", ".next", ".DS_Store", "package.json"]);
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (dest === root && SKIP.has(entry.name)) continue;
+    if (entry.name === ".DS_Store") continue;
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name === "gitignore" ? ".gitignore" : entry.name);
+    if (entry.isDirectory()) copyTemplateProject(srcPath, destPath, root);
+    else if (fs.existsSync(destPath)) console.log(`[jops-core] Kept the existing ${path.relative(root, destPath)}`);
+    else fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+// Creates the template's package.json, or merges its dependencies and scripts
+// into an existing one: existing entries (e.g. an installed jops-core) are kept.
+function mergeTemplatePackageJson(templatePath, targetPath) {
+  const template = JSON.parse(fs.readFileSync(templatePath, "utf8"));
+  if (!fs.existsSync(targetPath)) {
+    fs.writeFileSync(targetPath, JSON.stringify(template, null, 2) + "\n", "utf8");
+    console.log("[jops-core] Created package.json");
+    return;
+  }
+  const pkg = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+  pkg.private ??= true;
+  // `npm init -y` writes "type": "commonjs", which makes Next.js (Turbopack)
+  // reject the project's ES module sources; Next.js projects have no "type".
+  if (pkg.type === "commonjs") {
+    delete pkg.type;
+    console.log('[jops-core] Removed "type": "commonjs" from package.json (Next.js uses ES modules)');
+  }
+  for (const section of ["dependencies", "devDependencies"]) {
+    for (const [name, spec] of Object.entries(template[section] ?? {})) {
+      const existing = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+      if (existing) {
+        if (name === "jops-core") console.log(`[jops-core] Kept the installed jops-core (${existing})`);
+        continue;
+      }
+      pkg[section] = { ...pkg[section], [name]: spec };
+    }
+  }
+  for (const [name, command] of Object.entries(template.scripts ?? {})) {
+    const existing = pkg.scripts?.[name];
+    if (existing && existing !== command) {
+      console.log(`[jops-core] Kept the existing "${name}" script (${existing}); the template uses "${command}"`);
+      continue;
+    }
+    pkg.scripts = { ...pkg.scripts, [name]: command };
+  }
+  fs.writeFileSync(targetPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+  console.log("[jops-core] Added the Next.js dependencies and scripts to package.json");
+}
+
+// ─── template selection ──────────────────────────────────────────────────────
+// Asked before init writes anything, because the Next.js template creates its
+// own project folder instead of configuring the current one.
+
+async function askTemplate() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve) => rl.question(
+    "\nCreate JOPS project from existing templates:\n" +
+    "  1. Empty JOPS project (basic skeleton for JOPS project architecture)\n" +
+    "  2. Hello World JOPS project (an example project utilizing all features)\n" +
+    "  3. Next.js JOPS Embedded SPA (a Next.js project hosting a JOPS SPA)\n" +
+    "  4. None (I'll create my own architecture)\n" +
+    "Enter choice (1-4): ",
+    resolve,
+  ));
+  rl.close();
+  return answer.trim();
+}
+
+const choice = command === "init" ? await askTemplate() : null;
+
+// ─── init: Next.js JOPS Embedded SPA (template 3) ────────────────────────────
+
+if (command === "init" && choice === "3") {
+  const cwd = process.cwd();
+  const templateDir = path.join(__dirname, "../templates/nextjs-jops-spa");
+  // Paths that would clash with an existing project: nothing is written then.
+  const conflicts = [
+    "next.config.ts", "next.config.js", "next.config.mjs",
+    "tsconfig.json", "src/app", "public/jops-spa", "data/quotes.json",
+  ].filter((p) => fs.existsSync(path.join(cwd, p)));
+
+  if (isHybrid) {
+    console.error(`[jops-core] This is a ${type} project; create the Next.js project in another folder.`);
+    process.exitCode = 1;
+  } else if (conflicts.length) {
+    console.error(`[jops-core] This folder already has ${conflicts.join(", ")}. Nothing was changed.`);
+    console.error("            Run init in an empty folder (or a fresh npm project) to create the Next.js project.");
+    process.exitCode = 1;
+  } else {
+    copyTemplateProject(templateDir, cwd);
+    mergeTemplatePackageJson(path.join(templateDir, "package.json"), path.join(cwd, "package.json"));
+    console.log("[jops-core] Created the Next.js JOPS Embedded SPA project in this folder.");
+
+    const libDir = path.join(cwd, "public", "lib");
+    fs.mkdirSync(libDir, { recursive: true });
+    fs.copyFileSync(path.join(__dirname, "../lib/jops-core.min.js"), path.join(libDir, "jops-core.min.js"));
+    console.log("[jops-core] Vendored jops-core.min.js → public/lib/jops-core.min.js");
+
+    console.log("[jops-core] Installing dependencies (npm install)…");
+    const install = spawnSync("npm", ["install"], {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    if (install.status !== 0) {
+      console.warn("[jops-core] npm install did not complete. Run it yourself: npm install");
+    }
+    console.log("");
+    console.log("[jops-core] Next steps:");
+    console.log("            npm run dev");
+    console.log("            open http://localhost:3000/about and http://localhost:3000/jops-spa");
+  }
+}
+
 // ─── index.html helpers (hybrid projects) ────────────────────────────────────
 
 // Same policy as Cordova's default, plus 'unsafe-inline' for the inline import map
@@ -242,7 +370,7 @@ function schemeWarnings(xml) {
 
 // ─── init ────────────────────────────────────────────────────────────────────
 
-if (command === "init") {
+if (command === "init" && choice !== "3") {
   fs.mkdirSync(webRoot, { recursive: true });
   if (isHybrid) {
     console.log(`[jops-core] ${forced ? "Using" : "Detected"} ${type} project → web folder: ${rel(webRoot)}/`);
@@ -405,22 +533,10 @@ ${cordovaBody}${MODULE_SCRIPT}
     if (changed) fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
   }
 
-  // Template selection
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const ask = (q) => new Promise(resolve => rl.question(q, resolve));
-
-  const choice = await ask(
-    "\nCreate JOPS project from existing templates:\n" +
-    "  1. Empty JOPS project (basic skeleton for JOPS project architecture)\n" +
-    "  2. Hello World JOPS project (an example project utilizing all features)\n" +
-    "  3. None (I'll create my own architecture)\n" +
-    "Enter choice (1-3): "
-  );
-  rl.close();
-
+  // Template choice: asked at the start (see askTemplate()).
   // 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()) &&
+  if (type === "cordova" && ["1", "2"].includes(choice) &&
       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`);
@@ -430,7 +546,7 @@ ${cordovaBody}${MODULE_SCRIPT}
   }
 
   const templateSrc = path.join(__dirname, "../templates");
-  if (choice.trim() === "1") {
+  if (choice === "1") {
     copyDir(path.join(templateSrc, "empty"), webRoot);
     // Add data-app to the module script in index.html
     let html = fs.readFileSync(indexPath, "utf8");
@@ -440,7 +556,7 @@ ${cordovaBody}${MODULE_SCRIPT}
     );
     fs.writeFileSync(indexPath, html, "utf8");
     console.log("[jops-core] Created empty JOPS project skeleton.");
-  } else if (choice.trim() === "2") {
+  } else if (choice === "2") {
     copyDir(path.join(templateSrc, "hello-world"), webRoot);
     let html = fs.readFileSync(indexPath, "utf8");
     html = html.replace(
@@ -457,7 +573,9 @@ ${cordovaBody}${MODULE_SCRIPT}
 // ─── update ──────────────────────────────────────────────────────────────────
 
 if (command === "update") {
-  const libDir = path.join(webRoot, "lib");
+  // A Next.js project serves the library from public/lib/.
+  const libRoot = type === "web" && isNextProject(projectRoot) ? path.join(projectRoot, "public") : webRoot;
+  const libDir = path.join(libRoot, "lib");
   const vendorDest = path.join(libDir, "jops-core.min.js");
   const vendorSrc = path.join(__dirname, "../lib/jops-core.min.js");
 

package/lib/jops-core.d.ts

@@ -1,3 +1,32 @@
+/**
+ * Starts a JOPS app inside a given element instead of `<body>`. Used by hosts
+ * that control when and where the app runs, such as `<JopsApp>` in Next.js
+ * (jops-core loaded with `data-host`, which exposes `window.JOPS.mount`).
+ * @param {{ app: string, root: HTMLElement }} options - `app`: URL of the app's
+ *   entry module (default export is the App class); `root`: element the app's
+ *   root view renders into.
+ * @returns {Promise<object>} The App instance.
+ * @example
+ * await mount({ app: "/quotes/App.js", root: document.getElementById("quotes") });
+ */
+export declare function mount({ app, root }: {
+    app: string;
+    root: HTMLElement;
+}): Promise<object>;
+/**
+ * Ends the hosted app completely, like closing a standalone app: destroys the
+ * Router (listeners, singleton, routes, stacked views) and every view, empties
+ * the host root, clears the Store and the EventBus, and restores the host's
+ * history methods. The current URL and history entry are left alone: they
+ * belong to the host page. Safe to call more than once.
+ *
+ * Called by the Router itself when history leaves the app's page (Back past
+ * the entry the app was launched from, or a host link to another page), and
+ * by hosts such as `<JopsApp>` when they remove the app.
+ * @example
+ * window.JOPS.unmount();
+ */
+export declare function unmount(): void;
 declare class RawHTML {
     html: any;
     constructor(html: any);
@@ -26,13 +55,43 @@ export declare function layout(strings: TemplateStringsArray, ...values: any[]):
  * Wraps a single child element for reading and writing.
  */
 declare class Element {
-    element: any;
-    constructor(domNode: any, id: any);
+    #private;
+    id: string;
+    inert: boolean;
+    element: globalThis.Element;
     /**
-     * Sets the `innerHTML` of the element.
-     * @param {string} value - Plain text or HTML string.
+     * @param {HTMLElement[]} roots - The view's root elements, searched in order.
+     * @param {string} id - The id to look up; the first root that has it wins.
      */
-    set(value: string): void;
+    constructor(roots: HTMLElement[], id: string);
+    /**
+     * Wraps an element that was already found (used by `View.find(id)`).
+     * @param {HTMLElement} element
+     * @param {string} id
+     * @returns {Element}
+     */
+    static from(element: HTMLElement, id: string): Element;
+    /**
+     * Sets the `innerHTML` of the element. The value is not escaped: pass values
+     * from users or the network through the `layout` tag.
+     * @param {string} html - Plain text or HTML string.
+     * @returns {Element} This wrapper, for chaining.
+     * @example
+     * this.get("title").set(layout`${quote.number}`);
+     */
+    set(html: string): Element;
+    /**
+     * Sets an attribute, or removes it when `value` is `null` or `undefined`.
+     * An empty string sets a boolean attribute (`disabled`, `hidden`, `required`).
+     * @param {string} name - Attribute name, e.g. "href".
+     * @param {string|number|boolean|null} [value] - Attribute value.
+     * @returns {Element} This wrapper, for chaining.
+     * @example
+     * this.get("quote_id").set(layout`${q.number}`).attr("href", `#quote?id=${q.id}`);
+     * this.get("save").attr("disabled", "");    // set
+     * this.get("save").attr("disabled", null);  // remove
+     */
+    attr(name: string, value?: string | number | boolean | null): Element;
     /**
      * Returns the current `innerHTML` of the element.
      * @returns {string}
@@ -46,9 +105,16 @@ declare class Element {
  * 1. {@link View#loadLayout} — load or assign `this.layout`
  * 2. {@link View#inflate}    — parse `this.layout` into `this.domNode`
  * 3. {@link View#onLayout}   — DOM is live; add subviews, read initial data
- * 4. {@link View#onResume}   — view becomes visible; called again on every return navigation
+ * 4. {@link View#onResume}   — view becomes visible; called again on every return navigation,
+ *    and when the same route is shown again with new parameters
  * 5. {@link View#bindEvents} — wire `on*` attributes to class methods
  *
+ * Optional hooks, also called by the framework:
+ * - `onPause()`       — a different view comes to the front and this one stays alive
+ *   (hidden route, or covered by a stacked view). Not called when the view is destroyed
+ *   (Back from a stacked view, a stack closed by a flat link, unmount()).
+ * - `onBackPressed()` — Back navigation from this view (called before onPause() for routes).
+ *
  * @example
  * import { View, layout } from "jops-core";
  *
@@ -63,17 +129,35 @@ declare class Element {
  */
 export declare class View {
     #private;
+    _generation: number;
     subViews: any[];
     layout: any;
     style: string;
+    domNodes: any[];
     domNode: any;
+    _destroyed: boolean;
+    _borrowedDomNode: boolean;
     /**
      * @param {string} [layout] - Optional layout path or inline HTML string.
+     * @param {Record<string, string>} [props] - Input properties. A view declared
+     *   in a layout (`<Card jops src="…" title="Hi">`) gets them from the tag's
+     *   attributes automatically; a view created in code may pass them here.
      */
-    constructor(layout?: string);
+    constructor(layout?: string, props?: Record<string, string>);
+    /**
+     * The view's input properties (read-only): the attributes of its declared
+     * jops tag (except `jops`, `type="jops"`, `src`, `layout`, `path`,
+     * `jops-event-bind`), names in camelCase, values as strings; or the props
+     * passed to the constructor. `{}` when there are none.
+     * @returns {Readonly<Record<string, string>>}
+     */
+    get props(): Readonly<Record<string, string>>;
     /**
      * Override to load a layout file or set `this.layout` inline.
      * Called automatically by the framework before `inflate()`.
+     * Loads once per view: overlapping calls (with or without a path) wait for
+     * the load in progress, and once a layout is set later calls return at once.
+     * A failed load leaves the view unloaded, so it can be retried.
      * @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.
@@ -83,6 +167,7 @@ export declare class View {
     loadLayout(layout?: string): Promise<void>;
     /**
      * Injects a `.css` file link or an inline `<style>` tag into `<head>`, deduped.
+     * No effect in hosted mode (e.g. Next.js through `<JopsApp>`): the host owns the CSS.
      * @param {string} style - Path to a `.css` file, or a raw CSS string.
      */
     setStyle(style: string): void;
@@ -94,6 +179,19 @@ export declare class View {
      * this.get("username").set("Alice");
      */
     get(id: string): Element;
+    /**
+     * The view's root elements: every top-level element of its layout (a layout
+     * may have more than one), or the borrowed container of a root view.
+     * @returns {HTMLElement[]}
+     * @protected
+     */
+    protected _roots(): HTMLElement[];
+    /**
+     * Hides or shows every root element (used by the Router).
+     * @param {boolean} hidden
+     * @protected
+     */
+    protected _setHidden(hidden: boolean): void;
     /**
      * Wires `on*` HTML attributes on `[jops-event-bind]` elements to
      * same-named methods on this view instance.
@@ -108,6 +206,7 @@ export declare class View {
     /**
      * Appends `view` into the child element with `id="parentNode"` and runs its
      * full lifecycle (`onLayout` → `onResume` → `bindEvents`).
+     * A removed (destroyed) view is final: create a new instance to show it again.
      * @param {string} parentNode - The `id` of the container element inside `this.domNode`.
      * @param {View} view - The subview to mount.
      * @returns {Promise<void>}
@@ -121,14 +220,50 @@ export declare class View {
      * Removes the inline `display` override, restoring `this.domNode` visibility.
      */
     show(): void;
+    /**
+     * Every element with the given id across all root elements of the layout
+     * (and the DOM of its sub-views), in page order.
+     * @overload
+     * @param {string} id - Element id.
+     * @returns {Element[]}
+     * @example
+     * this.find("quote_id").forEach((el) => el.attr("tabindex", 0));
+     */
     /**
      * Depth-first search across the full subview subtree.
-     * @param {function(View): boolean} condition - Predicate to match against each view.
+     * @overload
+     * @param {(view: View) => boolean} condition - Predicate to match against each view.
      * @returns {View[]} Flat array of all matching views.
      * @example
      * const forms = root.find(v => v instanceof FormView);
      */
-    find(condition: Function): View[];
+    /**
+     * @param {string | ((view: View) => boolean)} arg
+     * @returns {Element[] | View[]}
+     */
+    find(id: string): Element[];
+    /**
+     * Every element with the given id across all root elements of the layout
+     * (and the DOM of its sub-views), in page order.
+     * @overload
+     * @param {string} id - Element id.
+     * @returns {Element[]}
+     * @example
+     * this.find("quote_id").forEach((el) => el.attr("tabindex", 0));
+     */
+    /**
+     * Depth-first search across the full subview subtree.
+     * @overload
+     * @param {(view: View) => boolean} condition - Predicate to match against each view.
+     * @returns {View[]} Flat array of all matching views.
+     * @example
+     * const forms = root.find(v => v instanceof FormView);
+     */
+    /**
+     * @param {string | ((view: View) => boolean)} arg
+     * @returns {Element[] | View[]}
+     */
+    find(condition: (view: View) => boolean): View[];
     /**
      * Recursively destroys the subview subtree: calls `destroy()` on all
      * subviews, removes `this.domNode` from the DOM, and nulls references.
@@ -141,11 +276,21 @@ export declare class View {
     removeSubView(view: View): void;
     /**
      * Inserts `view` at `index` within `this.domNode` and runs its full lifecycle.
+     * A removed (destroyed) view is final: create a new instance to show it again.
      * @param {View} view - The subview to insert.
      * @param {number} index - Zero-based insertion position.
      * @returns {Promise<void>}
      */
     insertSubView(view: View, index: number): Promise<void>;
+    /**
+     * Final lifecycle steps for a sub-view declared in this view's layout,
+     * called by `render()` after its `onLayout()`. Router overrides it so a
+     * route is resumed only when it is shown.
+     * @param {View} subView
+     * @returns {Promise<void>}
+     * @protected
+     */
+    protected _startSubView(subView: View): Promise<void>;
     /**
      * Mounts the view to the DOM, resolves all nested `[jops]` view
      * elements and `<Router>` declarations, and runs each one's full lifecycle.
@@ -159,30 +304,83 @@ export declare class View {
  * Static pub/sub event bus for cross-view communication.
  * All methods are static — no instance needed.
  *
+ * A subscription with an owner (a view) is removed automatically when the
+ * owner is destroyed; a global subscription (no owner) stays until it is
+ * unsubscribed (the developer's responsibility).
+ *
  * @example
- * EventBus.subscribe("user:login", data => console.log(data.name));
+ * EventBus.subscribe(this, "quotes:changed", (q) => this.refresh(q)); // owned
+ * EventBus.subscribe("user:login", onLogin);                          // global
  * EventBus.send("user:login", { name: "Alice" });
  */
 export declare class EventBus {
     #private;
     /**
-     * Registers a listener for the named event.
+     * Registers a global listener; unsubscribe it with `unsubscribe()`.
+     * @overload
+     * @param {string} event - Event name.
+     * @param {(data: any) => void} callback - Handler called with the event payload.
+     * @returns {void}
+     */
+    /**
+     * Registers a listener owned by `owner` (usually a view): it is removed
+     * automatically when the owner is destroyed.
+     * @overload
+     * @param {object} owner - The object owning the subscription, e.g. `this`.
+     * @param {string} event - Event name.
+     * @param {(data: any) => void} callback - Handler called with the event payload.
+     * @returns {void}
+     */
+    /**
+     * @param {...*} args - `(event, callback)` or `(owner, event, callback)`.
+     * @returns {void}
+     */
+    static subscribe(event: string, callback: (data: any) => void): void;
+    /**
+     * Registers a global listener; unsubscribe it with `unsubscribe()`.
+     * @overload
+     * @param {string} event - Event name.
+     * @param {(data: any) => void} callback - Handler called with the event payload.
+     * @returns {void}
+     */
+    /**
+     * Registers a listener owned by `owner` (usually a view): it is removed
+     * automatically when the owner is destroyed.
+     * @overload
+     * @param {object} owner - The object owning the subscription, e.g. `this`.
      * @param {string} event - Event name.
-     * @param {function(*): void} callback - Handler called with the event payload.
+     * @param {(data: any) => void} callback - Handler called with the event payload.
+     * @returns {void}
      */
-    static subscribe(event: string, callback: Function): void;
     /**
-     * Fires the named event to all subscribers.
+     * @param {...*} args - `(event, callback)` or `(owner, event, callback)`.
+     * @returns {void}
+     */
+    static subscribe(owner: object, event: string, callback: (data: any) => void): void;
+    /**
+     * Fires the named event to all subscribers. Subscriptions of destroyed
+     * owners are skipped and removed (a safety net: `destroy()` normally
+     * removes them first).
      * @param {string} event - Event name.
      * @param {*} [data] - Optional payload passed to every subscriber.
      */
     static send(event: string, data?: any): void;
     /**
-     * Removes a specific listener by reference.
+     * Removes a specific listener by reference (global or owned).
      * @param {string} event - Event name.
      * @param {function(*): void} callback - The exact function reference passed to `subscribe`.
      */
     static unsubscribe(event: string, callback: Function): void;
+    /**
+     * Removes every subscription owned by `owner`, across all events (called by
+     * `View.destroy()`). Global subscriptions are not touched.
+     * @param {object} owner - The owner passed to `subscribe(owner, event, callback)`.
+     */
+    static unsubscribeAll(owner: object): void;
+    /**
+     * Removes every listener of every event (called by `unmount()`).
+     */
+    static clear(): void;
 }
 /**
  * App-wide runtime state container. Singleton. No reactivity.
@@ -244,7 +442,10 @@ export declare class Router extends View {
     routes: {};
     _navStack: any[];
     _baseView: any;
+    _defaultPath: string;
+    _pathname: string;
     _idx: any;
+    _historyListener: () => void;
     _currentView: any;
     /**
      * Returns the single Router instance after it has been rendered.
@@ -253,6 +454,15 @@ export declare class Router extends View {
     static singleton(): Router;
     constructor(routerDomNode: any);
     onLayout(): Promise<void>;
+    /**
+     * Routes only get their events bound while the Router renders; `onResume()`
+     * runs when a route is shown (`_switchTo()` and the transitions), so hidden
+     * routes are not resumed at startup.
+     * @param {View} subView
+     * @returns {Promise<void>}
+     * @protected
+     */
+    protected _startSubView(subView: View): Promise<void>;
     initRouter(): void;
     /**
      * Single entry point for popstate and hashchange. Decides the direction
@@ -261,7 +471,33 @@ export declare class Router extends View {
     _onHistoryChange(): void;
     _onBack(): void;
     _onForward(): void;
+    /** Destroys every stacked navigate() view (switching to a flat route). */
+    _closeStack(): void;
+    /**
+     * onPause() on the view leaving the front: a different view is coming to
+     * the front and the current one stays alive (hidden or covered). Not used
+     * when a view is destroyed (stack pop on Back, _closeStack(), unmount()).
+     * @param {View} incoming
+     */
+    _pauseCurrent(incoming: View): void;
     _switchToHash(): void;
+    /**
+     * Replaces the current entry's empty hash with the default (first) route,
+     * keeping the existing history state, and shows that route.
+     */
+    _switchToDefault(): void;
+    /**
+     * Removes the history listeners, destroys the routes and stacked views and
+     * clears the singleton. Called by `unmount()`; safe to call more than once.
+     */
+    destroy(): void;
+    /** pushState/replaceState marked as JOPS's own (see installHostHistoryHook). */
+    _history(method: any, state: any, url: any): void;
+    /**
+     * Hosted mode: called after the host changed the URL with pushState or
+     * replaceState (no browser event fires for those).
+     */
+    _onHostNavigation(): 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>;