@crossbind/extension-page-navigation 0.0.0-stage → 2.0.0-beta.69

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buğra Sarı and crossbind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @crossbind/extension-page-navigation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Loads the app's pages and the origins it lists, and opens other links the user follows in the browser.
+
+An app has it by having `@crossbind/core-app-host`, which lists it as a dependency: there is nothing to install or list.
+
+## What it does
+
+The app's own pages load, and so do those of the origins `app.navigation.load` lists. A link to another origin that the
+user follows opens in the default browser; any other navigation loads nothing. It holds `page-authentication` as well,
+for which it answers nothing, so the host cancels an HTTP sign-in and a certificate error: an extension that takes
+`page-authentication` answers them.
+
+## Options
+
+`app.navigation.load` lists the origins that load in the app, as `['https://login.example.com']`.
+
+## Platforms
+
+macOS, iOS, Linux, Windows and Android.
+
+## Replace or leave out
+
+It holds the roles `page-authentication` and `page-navigation`. An extension that gives `replaces: 'page-authentication'` takes that role alone, and this one goes on with the rest; `app: { without: ['page-navigation'] }` in `crossbind.config.js` leaves it out. Leaving it out while `app.navigation` is set stops the build. [The guide](https://crossbind.dev/guide/extensions/#replace) shows how, and [extensions.md](https://github.com/crossbind/crossbind/blob/main/docs/api/extensions.md#the-hosts-own-extensions) what a replacement answers.
+
+[extensions.md](https://github.com/crossbind/crossbind/blob/main/docs/api/extensions.md#the-pages-requests) has the hooks a replacement answers.

package/crossbind.extension.js

@@ -0,0 +1,36 @@
+// The origins whose pages load in the app beside its own, as app.navigation.load lists them: http and https ones alone,
+// each as a URL's origin is, as 'https://login.example.com'.
+function checkedNavigation(navigation) {
+    if (navigation === null || typeof navigation !== 'object' || Array.isArray(navigation)) {
+        throw new Error(`crossbind: app.navigation ${JSON.stringify(navigation)} is no object, as { load: ['https://login.example.com'] } is.`);
+    }
+    const unknown = Object.keys(navigation).filter((key) => key !== 'load');
+    if (unknown.length > 0) throw new Error(`crossbind: app.navigation takes load alone; ${unknown.join(', ')} is none of it.`);
+    const load = navigation.load ?? [];
+    if (!Array.isArray(load)) throw new Error(`crossbind: app.navigation.load ${JSON.stringify(load)} is no list of origins, as ['https://login.example.com'] is.`);
+    for (const origin of load) {
+        const url = typeof origin === 'string' && URL.canParse(origin) ? new URL(origin) : null;
+        if (!url || !['http:', 'https:'].includes(url.protocol) || url.origin !== origin) {
+            throw new Error(`crossbind: app.navigation.load's ${JSON.stringify(origin)} is no http or https origin, as 'https://login.example.com' is, with no path, no default port and its host in lower case.`);
+        }
+    }
+    return { load: [...load] };
+}
+
+export default function pageNavigation() {
+    return {
+        name: 'page-navigation',
+        contract: 1,
+        root: import.meta.dirname,
+        holds: ['page-authentication', 'page-navigation'],
+        reads: ['navigation'],
+        fromApp: (api) => checkedNavigation(api.config.app.navigation ?? {}),
+        app: {
+            macos: { sources: ['native/navigation.cpp'] },
+            ios: { sources: ['native/navigation.cpp'] },
+            linux: { sources: ['native/navigation.cpp'] },
+            windows: { sources: ['native/navigation.cpp'] },
+            android: { sources: ['native/navigation.cpp'] },
+        },
+    };
+}

package/native/navigation.cpp

@@ -0,0 +1,32 @@
+#include "crossbind/extension.h"
+
+#include <algorithm>
+#include <string>
+#include <vector>
+
+namespace {
+
+// A URL's origin as the page's scripts name it: its scheme, its host and the port it names.
+std::string originOf(const std::string &url) {
+    const auto scheme = url.find("://");
+    if (scheme == std::string::npos) return "";
+    return url.substr(0, url.find_first_of("/?#", scheme + 3));
+}
+
+}  // namespace
+
+// The host's page-navigation: the origins app.navigation.load lists load in the app, a link to another its user follows
+// opens outside, and the rest loads nothing. An authentication and a certificate error get no owner, so the host
+// cancels each.
+void crossbind_extension_page_navigation(crossbind::Registry &registry) {
+    std::vector<std::string> loads;
+    const crossbind::Value options = registry.options();
+    const crossbind::Value &listed = options["load"];
+    if (listed.isArray()) {
+        for (const crossbind::Value &origin : listed.asArray()) loads.push_back(origin.asString());
+    }
+    registry.onNavigation([loads](const crossbind::Navigation &navigation) {
+        if (std::find(loads.begin(), loads.end(), originOf(navigation.url())) != loads.end()) return crossbind::NavigationAnswer::load;
+        return navigation.isUserInitiated() ? crossbind::NavigationAnswer::openOutside : crossbind::NavigationAnswer::refuse;
+    });
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@crossbind/extension-page-navigation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.0.0-beta.69",
+  "description": "crossbind app extension: loads the app's pages and the origins it lists, and opens other links the user follows in the browser.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/extensions/page-navigation#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./crossbind.extension.js": "./crossbind.extension.js"
+  },
+  "files": [
+    "crossbind.extension.js",
+    "native"
+  ],
+  "crossbind": {
+    "extension": "./crossbind.extension.js"
+  },
+  "keywords": [
+    "crossbind-extension",
+    "crossbind",
+    "page",
+    "navigation",
+    "app"
+  ]
 }