@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/native-build.js

@@ -0,0 +1,575 @@
+var {require}=import.meta;import { existsSync, mkdirSync, copyFileSync, chmodSync } from "node:fs";
+import { join, dirname, basename, resolve } from "node:path";
+import { spawn, execSync } from "node:child_process";
+import { tmpdir, homedir, platform as osPlatform } from "node:os";
+import { injectCraftBridge } from "./craft-bridge.js";
+import { processCraftComponents, CRAFT_COMPONENT_STYLES } from "./craft-components.js";
+import { renderTemplate } from "./render.js";
+export async function buildNative(config) {
+  const startTime = Date.now();
+  try {
+    if (!await Bun.file(config.input).exists())
+      return {
+        success: !1,
+        target: config.target || detectPlatform(),
+        format: config.format || "app",
+        error: `Input file not found: ${config.input}`
+      };
+    const target = config.target || detectPlatform(), format = config.format || getDefaultFormat(target), outputDir = config.output || join(process.cwd(), "dist", "native");
+    if (!existsSync(outputDir))
+      mkdirSync(outputDir, { recursive: !0 });
+    let html = await renderTemplate(config.input, {
+      context: config.context,
+      options: { isDev: !1 }
+    });
+    html = injectCraftBridge(html, { debug: config.verbose });
+    html = processCraftComponents(html);
+    if (!html.includes("craft-component-styles")) {
+      if (html.includes("</head>"))
+        html = html.replace("</head>", `${CRAFT_COMPONENT_STYLES}
+</head>`);
+    }
+    const appName = config.name || basename(config.input, ".stx"), appVersion = config.version || "1.0.0", craftPath = config.craftPath || await findCraftBinary();
+    if (!craftPath)
+      return {
+        success: !1,
+        target,
+        format,
+        error: "Craft binary not found. Please install Craft or specify craftPath."
+      };
+    if (config.verbose) {
+      console.log(`\uD83D\uDCE6 Building native app for ${target}...`);
+      console.log(`   Input: ${config.input}`);
+      console.log(`   Output: ${outputDir}`);
+      console.log(`   Craft: ${craftPath}`);
+    }
+    let result;
+    switch (target) {
+      case "macos":
+        result = await buildMacOS(html, appName, appVersion, outputDir, format, config, craftPath);
+        break;
+      case "windows":
+        result = await buildWindows(html, appName, appVersion, outputDir, format, config, craftPath);
+        break;
+      case "linux":
+        result = await buildLinux(html, appName, appVersion, outputDir, format, config, craftPath);
+        break;
+      case "ios":
+        result = await buildIOS(html, appName, appVersion, outputDir, config, craftPath);
+        break;
+      case "android":
+        result = await buildAndroid(html, appName, appVersion, outputDir, config, craftPath);
+        break;
+      default:
+        result = {
+          success: !1,
+          target,
+          format,
+          error: `Unsupported target: ${target}`
+        };
+    }
+    result.duration = Date.now() - startTime;
+    return result;
+  } catch (error) {
+    return {
+      success: !1,
+      target: config.target || detectPlatform(),
+      format: config.format || "app",
+      error: error.message,
+      duration: Date.now() - startTime
+    };
+  }
+}
+async function buildMacOS(html, appName, appVersion, outputDir, format, config, craftPath) {
+  const bundleId = config.bundleId || `com.stx.${appName.toLowerCase().replace(/[^a-z0-9]/g, "")}`, appBundlePath = join(outputDir, `${appName}.app`), contentsDir = join(appBundlePath, "Contents"), macOSDir = join(contentsDir, "MacOS"), resourcesDir = join(contentsDir, "Resources");
+  mkdirSync(macOSDir, { recursive: !0 });
+  mkdirSync(resourcesDir, { recursive: !0 });
+  const htmlPath = join(resourcesDir, "index.html");
+  await Bun.write(htmlPath, html);
+  let sidebarConfigPath = "";
+  if (config.sidebar?.enabled && config.sidebar?.config) {
+    sidebarConfigPath = join(resourcesDir, "sidebar-config.json");
+    await Bun.write(sidebarConfigPath, JSON.stringify(config.sidebar.config));
+  }
+  const sidebarFlags = config.sidebar?.enabled ? `--native-sidebar --sidebar-width ${config.sidebar?.width || 240} --sidebar-config "$(cat "$RESOURCES/sidebar-config.json")"` : "", menubarOnly = config.menubarOnly ?? config.systemTray;
+  if ((config.bundleStyle || (await supportsBundleManifest(craftPath) ? "executable" : "launcher")) === "executable") {
+    const executablePath = join(macOSDir, appName);
+    copyFileSync(craftPath, executablePath);
+    chmodSync(executablePath, 493);
+    const manifest = {
+      html: "index.html",
+      title: config.window?.title || appName,
+      width: config.window?.width || 1200,
+      height: config.window?.height || 800,
+      devTools: Boolean(config.devTools)
+    };
+    if (menubarOnly)
+      manifest.menubarOnly = !0;
+    else if (config.systemTray)
+      manifest.systemTray = !0;
+    if (config.window?.frameless)
+      manifest.frameless = !0;
+    if (config.window?.transparent)
+      manifest.transparent = !0;
+    if (config.window?.alwaysOnTop)
+      manifest.alwaysOnTop = !0;
+    if (config.window?.resizable === !1)
+      manifest.resizable = !1;
+    await Bun.write(join(resourcesDir, "craft.json"), `${JSON.stringify(manifest, null, 2)}
+`);
+  } else {
+    const craftBinaryDest = join(macOSDir, "craft");
+    copyFileSync(craftPath, craftBinaryDest);
+    chmodSync(craftBinaryDest, 493);
+    const sidebarFlags = config.sidebar?.enabled ? `--native-sidebar --sidebar-width ${config.sidebar?.width || 240} --sidebar-config "$(cat "$RESOURCES/sidebar-config.json")"` : "", launcherScript = `#!/bin/bash
+set -euo pipefail
+DIR="$( cd "$( dirname "\${BASH_SOURCE[0]}" )" && pwd )"
+RESOURCES="$DIR/../Resources"
+exec "$DIR/craft" --html-file "$RESOURCES/index.html" \\
+  ${[
+      `--title "${config.window?.title || appName}"`,
+      `--width ${config.window?.width || 1200}`,
+      `--height ${config.window?.height || 800}`,
+      menubarOnly ? "--menubar-only" : config.systemTray ? "--system-tray" : "",
+      config.devTools ? "" : "--no-devtools",
+      config.window?.frameless ? "--frameless" : "",
+      config.window?.transparent ? "--transparent" : "",
+      config.window?.alwaysOnTop ? "--always-on-top" : "",
+      config.window?.resizable === !1 ? "--no-resize" : "",
+      sidebarFlags
+    ].filter(Boolean).join(" \\\n  ")}
+`, launcherPath = join(macOSDir, appName);
+    await Bun.write(launcherPath, launcherScript);
+    chmodSync(launcherPath, 493);
+  }
+  const hasIcon = Boolean(config.icon && await Bun.file(config.icon).exists());
+  if (hasIcon)
+    copyFileSync(config.icon, join(resourcesDir, "AppIcon.icns"));
+  const plistEntries = {
+    CFBundleExecutable: appName,
+    CFBundleIdentifier: bundleId,
+    CFBundleName: appName,
+    CFBundleDisplayName: appName,
+    CFBundleShortVersionString: appVersion,
+    CFBundleVersion: appVersion,
+    CFBundlePackageType: "APPL",
+    CFBundleSignature: "????",
+    LSMinimumSystemVersion: config.minimumSystemVersion || "13.0",
+    NSHighResolutionCapable: !0,
+    NSSupportsAutomaticGraphicsSwitching: !0,
+    LSUIElement: config.menubarOnly ?? Boolean(config.systemTray),
+    ...hasIcon ? { CFBundleIconFile: "AppIcon" } : {},
+    ...config.category ? { LSApplicationCategoryType: config.category } : {},
+    ...config.copyright ? { NSHumanReadableCopyright: config.copyright } : {},
+    ...config.infoPlist || {}
+  };
+  await Bun.write(join(contentsDir, "Info.plist"), renderInfoPlist(plistEntries));
+  if (format === "dmg") {
+    const dmgPath = join(outputDir, `${appName}-${appVersion}.dmg`), dmgResult = await createDMG(appBundlePath, dmgPath, appName);
+    if (!dmgResult.success)
+      return { success: !1, target: "macos", format: "dmg", error: dmgResult.error };
+    return { success: !0, target: "macos", format: "dmg", outputPath: dmgPath };
+  }
+  return { success: !0, target: "macos", format: "app", outputPath: appBundlePath };
+}
+async function supportsBundleManifest(craftPath) {
+  try {
+    const proc = Bun.spawn([craftPath, "--version"], { stdout: "pipe", stderr: "pipe" }), [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text()
+    ]);
+    await proc.exited;
+    const version = `${stdout}
+${stderr}`.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!version)
+      return !1;
+    const [major, minor, patch] = version.slice(1).map(Number);
+    if (major > 0 || minor > 0)
+      return !0;
+    return patch >= 57;
+  } catch {
+    return !1;
+  }
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function renderInfoPlist(entries) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+${Object.entries(entries).map(([key, value]) => {
+    const rendered = typeof value === "boolean" ? `<${value}/>` : typeof value === "number" ? `<integer>${value}</integer>` : `<string>${escapeXml(String(value))}</string>`;
+    return `    <key>${escapeXml(key)}</key>
+    ${rendered}`;
+  }).join(`
+`)}
+</dict>
+</plist>
+`;
+}
+async function buildWindows(html, appName, appVersion, outputDir, format, config, craftPath) {
+  const appDir = join(outputDir, appName);
+  mkdirSync(appDir, { recursive: !0 });
+  const htmlPath = join(appDir, "index.html");
+  await Bun.write(htmlPath, html);
+  copyFileSync(craftPath, join(appDir, "craft.exe"));
+  const launcherBat = `@echo off
+set DIR=%~dp0
+"%DIR%craft.exe" --html-file "%DIR%index.html" ^
+  --title "${config.window?.title || appName}" ^
+  --width ${config.window?.width || 1200} ^
+  --height ${config.window?.height || 800} ^
+  ${config.systemTray ? "--system-tray" : ""} ^
+  ${config.devTools ? "" : "--no-devtools"}
+`;
+  await Bun.write(join(appDir, `${appName}.bat`), launcherBat);
+  if (format === "zip") {
+    const zipPath = join(outputDir, `${appName}-${appVersion}-windows.zip`), zipResult = await createZip(appDir, zipPath);
+    if (!zipResult.success)
+      return { success: !1, target: "windows", format: "zip", error: zipResult.error };
+    return { success: !0, target: "windows", format: "zip", outputPath: zipPath };
+  }
+  return { success: !0, target: "windows", format: "app", outputPath: appDir };
+}
+async function buildLinux(html, appName, appVersion, outputDir, format, config, craftPath) {
+  const appDir = join(outputDir, appName);
+  mkdirSync(appDir, { recursive: !0 });
+  const htmlPath = join(appDir, "index.html");
+  await Bun.write(htmlPath, html);
+  const craftDest = join(appDir, "craft");
+  copyFileSync(craftPath, craftDest);
+  chmodSync(craftDest, 493);
+  const launcherScript = `#!/bin/bash
+set -euo pipefail
+DIR="$( cd "$( dirname "\${BASH_SOURCE[0]}" )" && pwd )"
+exec "$DIR/craft" --html-file "$DIR/index.html" \\
+  --title "${config.window?.title || appName}" \\
+  --width ${config.window?.width || 1200} \\
+  --height ${config.window?.height || 800} \\
+  ${config.systemTray ? "--system-tray" : ""} \\
+  ${config.devTools ? "" : "--no-devtools"}
+`, launcherPath = join(appDir, appName.toLowerCase());
+  await Bun.write(launcherPath, launcherScript);
+  chmodSync(launcherPath, 493);
+  const desktopFile = `[Desktop Entry]
+Type=Application
+Name=${appName}
+Exec=${launcherPath}
+Terminal=false
+Categories=Utility;
+`;
+  await Bun.write(join(appDir, `${appName.toLowerCase()}.desktop`), desktopFile);
+  if (format === "deb") {
+    const debPath = join(outputDir, `${appName.toLowerCase()}_${appVersion}_amd64.deb`), debResult = await createDEB(appDir, debPath, appName, appVersion, config);
+    if (!debResult.success)
+      return { success: !1, target: "linux", format: "deb", error: debResult.error };
+    return { success: !0, target: "linux", format: "deb", outputPath: debPath };
+  }
+  if (format === "appimage") {
+    const appImagePath = join(outputDir, `${appName}-${appVersion}-x86_64.AppImage`), appImageResult = await createAppImage(appDir, appImagePath, appName, config);
+    if (!appImageResult.success)
+      return { success: !1, target: "linux", format: "appimage", error: appImageResult.error };
+    return { success: !0, target: "linux", format: "appimage", outputPath: appImagePath };
+  }
+  return { success: !0, target: "linux", format: "app", outputPath: appDir };
+}
+async function buildIOS(_html, appName, _appVersion, _outputDir, _config, _craftPath) {
+  return {
+    success: !1,
+    target: "ios",
+    format: "ipa",
+    error: `iOS build requires Xcode and additional setup. Use 'stx init:ios ${appName}' to create an iOS project.`
+  };
+}
+async function buildAndroid(_html, appName, _appVersion, _outputDir, _config, _craftPath) {
+  return {
+    success: !1,
+    target: "android",
+    format: "apk",
+    error: `Android build requires Android SDK and additional setup. Use 'stx init:android ${appName}' to create an Android project.`
+  };
+}
+async function findCraftBinary() {
+  if (process.env.CRAFT_BIN && await Bun.file(process.env.CRAFT_BIN).exists())
+    return process.env.CRAFT_BIN;
+  const possiblePaths = [
+    join(process.cwd(), "../../craft/packages/zig/zig-out/bin/craft"),
+    join(process.cwd(), "../craft/packages/zig/zig-out/bin/craft"),
+    join(homedir(), "Code/Tools/craft/packages/zig/zig-out/bin/craft"),
+    join(homedir(), "Code/craft/packages/zig/zig-out/bin/craft"),
+    "/usr/local/bin/craft",
+    "/usr/bin/craft",
+    join(homedir(), ".local/bin/craft"),
+    join(process.env.LOCALAPPDATA || "", "craft", "craft.exe"),
+    join(process.env.PROGRAMFILES || "", "craft", "craft.exe")
+  ];
+  for (const path of possiblePaths)
+    if (await Bun.file(path).exists())
+      return path;
+  try {
+    const craftPath = execSync("which craft 2>/dev/null || where craft 2>nul", { encoding: "utf-8" }).trim().split(`
+`)[0];
+    if (craftPath && await Bun.file(craftPath).exists())
+      return craftPath;
+  } catch {}
+  return null;
+}
+function detectPlatform() {
+  switch (osPlatform()) {
+    case "darwin":
+      return "macos";
+    case "win32":
+      return "windows";
+    default:
+      return "linux";
+  }
+}
+function getDefaultFormat(target) {
+  switch (target) {
+    case "macos":
+      return "app";
+    case "windows":
+      return "zip";
+    case "linux":
+      return "appimage";
+    case "ios":
+      return "ipa";
+    case "android":
+      return "apk";
+    default:
+      return "app";
+  }
+}
+async function createDMG(appBundlePath, outputPath, volumeName) {
+  return new Promise((resolve) => {
+    const proc = spawn("hdiutil", [
+      "create",
+      "-volname",
+      volumeName,
+      "-srcfolder",
+      appBundlePath,
+      "-ov",
+      "-format",
+      "UDZO",
+      outputPath
+    ]);
+    proc.on("close", (code) => {
+      if (code === 0)
+        resolve({ success: !0 });
+      else
+        resolve({ success: !1, error: `hdiutil exited with code ${code}` });
+    });
+    proc.on("error", (err) => {
+      resolve({ success: !1, error: err.message });
+    });
+  });
+}
+async function createZip(sourceDir, outputPath) {
+  return new Promise((resolve) => {
+    const proc = spawn("zip", ["-r", outputPath, "."], { cwd: sourceDir });
+    proc.on("close", (code) => {
+      if (code === 0)
+        resolve({ success: !0 });
+      else
+        resolve({ success: !1, error: `zip exited with code ${code}` });
+    });
+    proc.on("error", (err) => {
+      resolve({ success: !1, error: err.message });
+    });
+  });
+}
+async function createDEB(appDir, outputPath, appName, appVersion, config) {
+  return new Promise((resolve) => {
+    try {
+      const tempDir = join(tmpdir(), `stx-deb-${Date.now()}`), debianDir = join(tempDir, "DEBIAN"), binDir = join(tempDir, "usr", "bin"), shareDir = join(tempDir, "usr", "share", "applications"), dataDir = join(tempDir, "usr", "share", appName.toLowerCase());
+      mkdirSync(debianDir, { recursive: !0 });
+      mkdirSync(binDir, { recursive: !0 });
+      mkdirSync(shareDir, { recursive: !0 });
+      mkdirSync(dataDir, { recursive: !0 });
+      const files = require("fs").readdirSync(appDir);
+      for (const file of files)
+        copyFileSync(join(appDir, file), join(dataDir, file));
+      const launcherScript = `#!/bin/bash
+exec /usr/share/${appName.toLowerCase()}/${appName.toLowerCase()} "$@"`;
+      require("fs").writeFileSync(join(binDir, appName.toLowerCase()), launcherScript);
+      chmodSync(join(binDir, appName.toLowerCase()), 493);
+      const control = `Package: ${appName.toLowerCase()}
+Version: ${appVersion}
+Section: utils
+Priority: optional
+Architecture: amd64
+Depends: libgtk-3-0, libwebkit2gtk-4.0-37
+Maintainer: ${config.author || "Unknown"}
+Description: ${config.description || appName}
+`;
+      require("fs").writeFileSync(join(debianDir, "control"), control);
+      const proc = spawn("dpkg-deb", ["--build", tempDir, outputPath]);
+      proc.on("close", (code) => {
+        require("fs").rmSync(tempDir, { recursive: !0, force: !0 });
+        if (code === 0)
+          resolve({ success: !0 });
+        else
+          resolve({ success: !1, error: `dpkg-deb exited with code ${code}` });
+      });
+      proc.on("error", (err) => {
+        require("fs").rmSync(tempDir, { recursive: !0, force: !0 });
+        resolve({ success: !1, error: err.message });
+      });
+    } catch (error) {
+      resolve({ success: !1, error: error.message });
+    }
+  });
+}
+async function createAppImage(appDir, outputPath, appName, config) {
+  return new Promise((resolve) => {
+    try {
+      const tempDir = join(tmpdir(), `stx-appimage-${Date.now()}`), appDirPath = join(tempDir, `${appName}.AppDir`), usrDir = join(appDirPath, "usr"), binDir = join(usrDir, "bin"), shareDir = join(usrDir, "share");
+      mkdirSync(binDir, { recursive: !0 });
+      mkdirSync(shareDir, { recursive: !0 });
+      const dataDir = join(shareDir, appName.toLowerCase());
+      mkdirSync(dataDir, { recursive: !0 });
+      const files = require("fs").readdirSync(appDir);
+      for (const file of files)
+        copyFileSync(join(appDir, file), join(dataDir, file));
+      const appRun = `#!/bin/bash
+SELF=$(readlink -f "$0")
+HERE=\${SELF%/*}
+export PATH="\${HERE}/usr/bin:\${PATH}"
+exec "\${HERE}/usr/share/${appName.toLowerCase()}/${appName.toLowerCase()}" "$@"
+`;
+      require("fs").writeFileSync(join(appDirPath, "AppRun"), appRun);
+      chmodSync(join(appDirPath, "AppRun"), 493);
+      const desktop = `[Desktop Entry]
+Type=Application
+Name=${appName}
+Exec=${appName.toLowerCase()}
+Terminal=false
+Categories=Utility;
+Icon=${appName.toLowerCase()}
+`;
+      require("fs").writeFileSync(join(appDirPath, `${appName.toLowerCase()}.desktop`), desktop);
+      const placeholderPng = Buffer.from([
+        137,
+        80,
+        78,
+        71,
+        13,
+        10,
+        26,
+        10,
+        0,
+        0,
+        0,
+        13,
+        73,
+        72,
+        68,
+        82,
+        0,
+        0,
+        0,
+        1,
+        0,
+        0,
+        0,
+        1,
+        8,
+        2,
+        0,
+        0,
+        0,
+        144,
+        119,
+        83,
+        222,
+        0,
+        0,
+        0,
+        12,
+        73,
+        68,
+        65,
+        84,
+        8,
+        215,
+        99,
+        248,
+        255,
+        255,
+        63,
+        0,
+        5,
+        254,
+        2,
+        254,
+        220,
+        204,
+        89,
+        231,
+        0,
+        0,
+        0,
+        0,
+        73,
+        69,
+        78,
+        68,
+        174,
+        66,
+        96,
+        130
+      ]);
+      require("fs").writeFileSync(join(appDirPath, `${appName.toLowerCase()}.png`), placeholderPng);
+      if (config.icon && existsSync(config.icon))
+        copyFileSync(config.icon, join(appDirPath, `${appName.toLowerCase()}.png`));
+      const proc = spawn("appimagetool", [appDirPath, outputPath], {
+        env: { ...process.env, ARCH: "x86_64" }
+      });
+      proc.on("close", (code) => {
+        require("fs").rmSync(tempDir, { recursive: !0, force: !0 });
+        if (code === 0) {
+          chmodSync(outputPath, 493);
+          resolve({ success: !0 });
+        } else
+          resolve({
+            success: !1,
+            error: `appimagetool exited with code ${code}. Install from https://appimage.github.io/appimagetool/`
+          });
+      });
+      proc.on("error", (err) => {
+        require("fs").rmSync(tempDir, { recursive: !0, force: !0 });
+        resolve({ success: !1, error: `appimagetool not found: ${err.message}` });
+      });
+    } catch (error) {
+      resolve({ success: !1, error: error.message });
+    }
+  });
+}
+export function getAvailableTargets() {
+  return [detectPlatform()];
+}
+export function getAvailableFormats(target) {
+  switch (target) {
+    case "macos":
+      return ["app", "dmg", "pkg"];
+    case "windows":
+      return ["app", "zip", "msi"];
+    case "linux":
+      return ["app", "deb", "rpm", "appimage"];
+    case "ios":
+      return ["ipa"];
+    case "android":
+      return ["apk"];
+    default:
+      return ["app"];
+  }
+}
+const nativeBuild = {
+  buildNative,
+  getAvailableTargets,
+  getAvailableFormats,
+  detectPlatform
+};
+export default nativeBuild;

package/dist/owned-routes.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Which same-origin paths the SPA router actually owns (stacksjs/stx#1864).
+ *
+ * With `interceptAllLinks` — hardcoded as the base default on the serve path —
+ * the router claimed EVERY same-origin relative anchor. `shouldIntercept()`
+ * filtered on protocol, target and a few opt-out attributes and had no notion
+ * of a route table, so a link to a non-page endpoint got fetched, failed to
+ * swap, and then fell back to a real navigation. The endpoint was hit twice:
+ *
+ *     Fetch     503  /api/auth/github/redirect
+ *     Document  503  /api/auth/github/redirect
+ *
+ * on an endpoint whose whole job is minting OAuth state. Worse, when such an
+ * endpoint returns a successful cross-origin redirect, `fetch` follows it and
+ * the router swaps a third-party document into the container.
+ *
+ * The only escape was `data-no-router`, which removes the anchor from routing
+ * entirely — one reporting app carries 17 of them, and every new link has to
+ * remember whether it needs one.
+ *
+ * The missing concept is a manifest of owned paths, which the file router
+ * already has. This ships the compiled matchers to the client so interception
+ * asks "is this a page I can render?" instead of "is this same-origin?".
+ *
+ * Regex SOURCES are shipped rather than patterns because the client runtime is
+ * a template literal (see CLAUDE.md item 41) — re-implementing the pattern
+ * compiler in there would mean maintaining a second matcher, in a file where
+ * every backslash has to be doubled, that must agree with this one forever.
+ *
+ * @module owned-routes
+ */
+/**
+ * Serialised matchers for every route the router can render.
+ *
+ * Empty when nothing could be discovered — callers MUST treat that as "unknown"
+ * and leave interception alone, never as "owns nothing". Shipping an empty list
+ * as authoritative would disable SPA navigation for a whole site, which is a
+ * far worse failure than the double-fetch this fixes.
+ */
+export declare function getOwnedRouteMatchers(pagesDir?: string): Promise<string[]>;
+/** Drop the memo, for tests and for a dev server that added a page. */
+export declare function clearOwnedRoutesCache(): void;

package/dist/owned-routes.js

@@ -0,0 +1,26 @@
+import { createRouter } from "./router.js";
+import { loadStxConfig } from "./config.js";
+const _cache = new Map;
+export async function getOwnedRouteMatchers(pagesDir) {
+  let dir = pagesDir;
+  if (!dir)
+    try {
+      dir = (await loadStxConfig())?.pagesDir || "pages";
+    } catch {
+      dir = "pages";
+    }
+  const key = dir, cached = _cache.get(key);
+  if (cached)
+    return cached;
+  let sources = [];
+  try {
+    sources = createRouter(".", { pagesDir: key }).map((route) => route.regex.source).filter(Boolean);
+  } catch {
+    sources = [];
+  }
+  _cache.set(key, sources);
+  return sources;
+}
+export function clearOwnedRoutesCache() {
+  _cache.clear();
+}