@apex-stack/core 0.7.7 → 0.8.0

package/dist/{build-C3FW7BTM.js → build-WKK4BCQI.js}

@@ -7,12 +7,13 @@ import {
   renderPage,
   resolveApexConfig,
   scanPages
-} from "./chunk-EVFABT7B.js";
+} from "./chunk-S3HCE23H.js";
 import "./chunk-PMLGY6Z3.js";
 
 // src/commands/build.ts
 import { cpSync, existsSync as existsSync3, mkdirSync, readdirSync as readdirSync3, rmSync, writeFileSync } from "fs";
 import { dirname, join as join3, resolve } from "path";
+import { renderFragment } from "@apex-stack/kit";
 import { apex as apex3 } from "@apex-stack/vite";
 import { defineCommand } from "citty";
 import { createServer as createViteServer } from "vite";
@@ -57,11 +58,20 @@ async function buildClient(root, routes, outDir, base = "/") {
         return [
           ...appCssRel ? [`import ${JSON.stringify(`/${appCssRel}`)}`] : [],
           `import Alpine from 'alpinejs'`,
+          `import { installNav } from '@apex-stack/core/client'`,
           ...storeIds.map((sid, i) => `import __s${i} from ${JSON.stringify(sid)}`),
+          // Registers this page's Alpine factory as a side effect. During client-side
+          // navigation this bundle is dynamic-imported again for the target page —
+          // the import runs (registering the new page), the boot guard below skips
+          // the one-time Alpine.start()/installNav so nothing double-initialises.
           `import ${JSON.stringify(pageId)}`,
-          "window.Alpine = Alpine",
-          ...storeIds.map((_, i) => `Alpine.store(__s${i}.name, __s${i}.factory())`),
-          "Alpine.start()"
+          "if (!window.__apexBooted) {",
+          "  window.__apexBooted = true",
+          "  window.Alpine = Alpine",
+          ...storeIds.map((_, i) => `  Alpine.store(__s${i}.name, __s${i}.factory())`),
+          "  Alpine.start()",
+          "  installNav()",
+          "}"
         ].join("\n");
       }
     }
@@ -222,12 +232,18 @@ var buildCommand = defineCommand({
         (id) => vite.ssrLoadModule(id)
       );
       const stores = await loadStores(root, (id) => vite.ssrLoadModule(id));
-      const { runtimeConfig, publicConfig } = await resolveApexConfig(
+      const { config, runtimeConfig, publicConfig } = await resolveApexConfig(
         root,
         (id) => vite.ssrLoadModule(id)
       );
+      const clientNav = config.clientNav !== false;
       const layoutsDir = join3(root, "layouts");
       const layouts = existsSync3(layoutsDir) ? readdirSync3(layoutsDir).filter((f) => f.endsWith(".alpine")).map((f) => f.replace(/\.alpine$/, "")) : [];
+      let loadingHtml;
+      if (!args.islands && clientNav && existsSync3(join3(root, "pages", "loading.alpine"))) {
+        const l = await vite.ssrLoadModule("/pages/loading.alpine");
+        loadingHtml = renderFragment(l.template, {}, l.scopeId, registry);
+      }
       for (const route of staticRoutes) {
         const common = {
           loadModule: (id) => vite.ssrLoadModule(id),
@@ -241,7 +257,13 @@ var buildCommand = defineCommand({
           publicConfig
         };
         const assets = hrefs.get(route.pageId);
-        const html = args.islands ? await renderIslandsPage(common) : await renderPage({ ...common, clientHref: assets?.js, clientCss: assets?.css });
+        const html = args.islands ? await renderIslandsPage(common) : await renderPage({
+          ...common,
+          clientHref: assets?.js,
+          clientCss: assets?.css,
+          clientNav,
+          loadingHtml
+        });
         const dest = join3(outDir, outFile(route.pattern));
         mkdirSync(dirname(dest), { recursive: true });
         writeFileSync(dest, html);
@@ -268,6 +290,8 @@ async function buildServerTarget(root, outDir, outLabel, routes) {
   const clientHrefs = await buildClient(root, routes, outDir);
   const server = await buildServer(root, routes, outDir);
   let runtimeConfig = { public: {} };
+  let clientNav = true;
+  let loadingHtml;
   const cfgVite = await createViteServer({
     root,
     appType: "custom",
@@ -278,6 +302,12 @@ async function buildServerTarget(root, outDir, outLabel, routes) {
     const resolved = await resolveApexConfig(root, (id) => cfgVite.ssrLoadModule(id));
     runtimeConfig = { public: {}, ...resolved.config.runtimeConfig ?? {} };
     if (!runtimeConfig.public) runtimeConfig.public = {};
+    clientNav = resolved.config.clientNav !== false;
+    if (clientNav && existsSync3(join3(root, "pages", "loading.alpine"))) {
+      const { registry } = await loadComponents(root, (id) => cfgVite.ssrLoadModule(id));
+      const l = await cfgVite.ssrLoadModule("/pages/loading.alpine");
+      loadingHtml = renderFragment(l.template, {}, l.scopeId, registry);
+    }
   } finally {
     await cfgVite.close();
   }
@@ -316,7 +346,9 @@ async function buildServerTarget(root, outDir, outLabel, routes) {
     components,
     api,
     middleware,
-    runtimeConfig
+    runtimeConfig,
+    clientNav,
+    loadingHtml
   };
   writeFileSync(join3(outDir, "apex-manifest.json"), JSON.stringify(manifest, null, 2));
   const pub = join3(root, "public");

package/dist/{chunk-EVFABT7B.js → chunk-S3HCE23H.js}

@@ -135,12 +135,12 @@ function renderHead(head) {
   const parts = [`<title>${head?.title ? escAttr(head.title) : "Apex JS"}</title>`];
   for (const m of head?.meta ?? []) {
     parts.push(
-      `<meta ${Object.entries(m).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} />`
+      `<meta ${Object.entries(m).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} data-apex-head />`
     );
   }
   for (const l of head?.link ?? []) {
     parts.push(
-      `<link ${Object.entries(l).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} />`
+      `<link ${Object.entries(l).map(([k, v]) => `${k}="${escAttr(v)}"`).join(" ")} data-apex-head />`
     );
   }
   return parts.join("\n  ");
@@ -207,7 +207,11 @@ async function renderPage(opts) {
     appCss: opts.appCss,
     clientCss: opts.clientCss,
     headTags: renderHead(head),
-    configScript: clientConfigScript(opts.publicConfig ?? {})
+    configScript: clientConfigScript(opts.publicConfig ?? {}),
+    // dev imports the page module by path; prod imports its hashed bundle.
+    moduleUrl: opts.clientHref ?? opts.pageId,
+    clientNav: opts.clientNav !== false,
+    loadingHtml: opts.loadingHtml
   });
   return opts.transformHtml ? opts.transformHtml(opts.url, doc) : doc;
 }
@@ -221,31 +225,44 @@ function shell({
   appCss,
   clientCss = [],
   headTags = "<title>Apex JS</title>",
-  configScript = ""
+  configScript = "",
+  moduleUrl,
+  clientNav = true,
+  loadingHtml
 }) {
   const storeImports = storeIds.map((id, i) => `  import __s${i} from ${JSON.stringify(id)}`).join("\n");
   const storeRegs = storeIds.map((_, i) => `  Alpine.store(__s${i}.name, __s${i}.factory())`).join("\n");
+  const navImport = clientNav ? `  import { installNav } from '@apex-stack/core/client'
+` : "";
+  const navInstall = clientNav ? `  installNav()
+` : "";
   const clientScript = clientHref ? `<script type="module" src="${clientHref}"></script>` : `<script type="module">
   import Alpine from 'alpinejs'
-${storeImports ? `${storeImports}
+${navImport}${storeImports ? `${storeImports}
 ` : ""}  import ${JSON.stringify(pageId)}
   window.Alpine = Alpine
 ${storeRegs ? `${storeRegs}
 ` : ""}  Alpine.start()
-</script>`;
+${navInstall}</script>`;
   const cssLinks = [...appCss ? [appCss] : [], ...clientCss].map((href) => `<link rel="stylesheet" href="${href}" />`).join("\n  ");
+  const moduleMeta = moduleUrl ? `
+  <meta name="apex:page-module" content="${escAttr(moduleUrl)}" />` : "";
+  const loadingTpl = loadingHtml ? `
+<template data-apex-loading>${loadingHtml}</template>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />${moduleMeta}
   ${cssLinks ? `${cssLinks}
   ` : ""}${headTags}
   <style>${css}</style>
 </head>
 <body>
+<div id="__apex" data-apex-root>
 ${body}
+</div>${loadingTpl}
 ${island}
 ${configScript}
 ${clientScript}
@@ -364,7 +381,8 @@ function walkAlpine(dir) {
 function scanPages(root) {
   const dir = join3(root, "pages");
   if (!existsSync3(dir)) return [];
-  const routes = walkAlpine(dir).map((abs) => {
+  const RESERVED = /* @__PURE__ */ new Set(["error.alpine", "loading.alpine"]);
+  const routes = walkAlpine(dir).filter((abs) => !RESERVED.has(relative(dir, abs).split(sep).join("/"))).map((abs) => {
     const rel = relative(dir, abs).split(sep).join("/");
     const pageId = `/pages/${rel}`;
     const parts = rel.replace(/\.alpine$/, "").split("/");

package/dist/{chunk-P6KQSPAV.js → chunk-TWAGSGFN.js}

@@ -90,6 +90,8 @@ async function offerExtension(choice) {
 }
 
 export {
+  cmpVersion,
   openInEditor,
+  promptYesNo,
   offerExtension
 };

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   offerExtension
-} from "./chunk-P6KQSPAV.js";
+} from "./chunk-TWAGSGFN.js";
 import {
   VERSION,
   banner,
@@ -147,13 +147,13 @@ var main = defineCommand2({
   },
   subCommands: {
     new: newCommand,
-    dev: () => import("./dev-SXOWAX4N.js").then((m) => m.devCommand),
-    build: () => import("./build-C3FW7BTM.js").then((m) => m.buildCommand),
-    start: () => import("./start-VBGP3HFC.js").then((m) => m.startCommand),
+    dev: () => import("./dev-3EVUK364.js").then((m) => m.devCommand),
+    build: () => import("./build-WKK4BCQI.js").then((m) => m.buildCommand),
+    start: () => import("./start-FIRWZ55Y.js").then((m) => m.startCommand),
     make: () => import("./make-VAYO5GWA.js").then((m) => m.makeCommand),
     add: () => import("./add-M3YLIFF5.js").then((m) => m.addCommand),
     theme: () => import("./theme-UUOIV44V.js").then((m) => m.themeCommand),
-    upgrade: () => import("./upgrade-KGUW3C3O.js").then((m) => m.upgradeCommand),
+    upgrade: () => import("./upgrade-YZN6TVNI.js").then((m) => m.upgradeCommand),
     migrate: () => import("./migrate-X6LIHMIE.js").then((m) => m.migrateCommand),
     mcp: () => import("./mcp-CH7L4GF3.js").then((m) => m.mcpCommand)
   },

package/dist/client.d.ts

@@ -1 +1 @@
-export { ActionOptions, ActionState, createAction, registerApexComponent } from '@apex-stack/kit/client';
+export { ActionOptions, ActionState, NavOptions, createAction, installNav, registerApexComponent } from '@apex-stack/kit/client';

package/dist/client.js

@@ -1,6 +1,7 @@
 // src/client.ts
-import { createAction, registerApexComponent } from "@apex-stack/kit/client";
+import { createAction, installNav, registerApexComponent } from "@apex-stack/kit/client";
 export {
   createAction,
+  installNav,
   registerApexComponent
 };

package/dist/{dev-SXOWAX4N.js → dev-3EVUK364.js}

@@ -24,7 +24,7 @@ var devCommand = defineCommand({
     process.stdout.write(banner());
     const sp = spinner(`Starting dev server${args.islands ? " (islands mode)" : ""}\u2026`);
     try {
-      const { startDevServer } = await import("./server-AV533LKD.js");
+      const { startDevServer } = await import("./server-UVY6DFK2.js");
       const { port: actual } = await startDevServer({ root, port, islands: Boolean(args.islands) });
       sp.succeed("Dev server ready");
       ready([

package/dist/index.d.ts

@@ -14,6 +14,11 @@ interface ApexConfig {
      * `APEX_PUBLIC_<KEY>` for `public` keys (camelCase ↔ SCREAMING_SNAKE).
      */
     runtimeConfig?: RuntimeConfig;
+    /**
+     * Client-side navigation (SPA link nav + prefetch + progress bar). On by
+     * default; set `false` to fall back to full-page loads.
+     */
+    clientNav?: boolean;
     [key: string]: unknown;
 }
 /** Author an `apex.config.ts`. Identity function — exists for types + discoverability. */

package/dist/{server-AV533LKD.js → server-UVY6DFK2.js}

@@ -1,6 +1,6 @@
 import {
   openInEditor
-} from "./chunk-P6KQSPAV.js";
+} from "./chunk-TWAGSGFN.js";
 import {
   loadComponents
 } from "./chunk-4VG3CZ6H.js";
@@ -19,7 +19,7 @@ import {
   renderPage,
   resolveApexConfig,
   scanPages
-} from "./chunk-EVFABT7B.js";
+} from "./chunk-S3HCE23H.js";
 import "./chunk-PMLGY6Z3.js";
 
 // src/dev/server.ts
@@ -28,6 +28,7 @@ import { createServer as createHttpServer } from "http";
 import { createRequire } from "module";
 import { join as join2, resolve } from "path";
 import { fileURLToPath, pathToFileURL } from "url";
+import { renderFragment } from "@apex-stack/kit";
 import { apex } from "@apex-stack/vite";
 import {
   createApp,
@@ -388,10 +389,11 @@ async function startDevServer(options) {
     const resolved = id[0] === "/" && !id.startsWith(options.root) ? join2(options.root, id).replace(/\\/g, "/") : id;
     return vite.ssrLoadModule(resolved);
   };
-  const { runtimeConfig, publicConfig } = await resolveApexConfig(
+  const { config, runtimeConfig, publicConfig } = await resolveApexConfig(
     options.root,
     (id) => ssrLoad(id)
   );
+  const clientNav = config.clientNav !== false;
   const app = createApp();
   app.use(fromNodeMiddleware(vite.middlewares));
   app.use(
@@ -463,6 +465,11 @@ async function startDevServer(options) {
         const stores = await loadStores(options.root, (id) => ssrLoad(id));
         const layoutsDir = join2(options.root, "layouts");
         const layouts = existsSync2(layoutsDir) ? readdirSync2(layoutsDir).filter((f) => f.endsWith(".alpine")).map((f) => f.replace(/\.alpine$/, "")) : [];
+        let loadingHtml;
+        if (!options.islands && clientNav && existsSync2(join2(options.root, "pages", "loading.alpine"))) {
+          const l = await ssrLoad("/pages/loading.alpine");
+          loadingHtml = renderFragment(l.template, {}, l.scopeId, registry);
+        }
         const render = options.islands ? renderIslandsPage : renderPage;
         const html = await render({
           loadModule: (id) => ssrLoad(id),
@@ -476,6 +483,8 @@ async function startDevServer(options) {
           layouts,
           runtimeConfig,
           publicConfig,
+          clientNav,
+          loadingHtml,
           locals: event.context.apexLocals ?? {},
           errorPageId: existsSync2(join2(options.root, "pages", "error.alpine")) ? "/pages/error.alpine" : void 0,
           transformHtml: (u, doc) => vite.transformIndexHtml(u, doc)

package/dist/{start-VBGP3HFC.js → start-FIRWZ55Y.js}

@@ -11,7 +11,7 @@ import {
   matchRoute,
   renderIslandsPage,
   renderPage
-} from "./chunk-EVFABT7B.js";
+} from "./chunk-S3HCE23H.js";
 import "./chunk-PMLGY6Z3.js";
 
 // src/commands/start.ts
@@ -133,6 +133,8 @@ async function startProdServer(options) {
         clientCss: route?.clientCss,
         runtimeConfig,
         publicConfig,
+        clientNav: manifest.clientNav !== false,
+        loadingHtml: manifest.loadingHtml,
         locals: event.context.apexLocals ?? {},
         errorPageId
       });

package/dist/{upgrade-KGUW3C3O.js → upgrade-YZN6TVNI.js}

@@ -1,6 +1,8 @@
 import {
-  offerExtension
-} from "./chunk-P6KQSPAV.js";
+  cmpVersion,
+  offerExtension,
+  promptYesNo
+} from "./chunk-TWAGSGFN.js";
 import {
   VERSION,
   banner,
@@ -8,12 +10,69 @@ import {
 } from "./chunk-QIXJSQLW.js";
 
 // src/commands/upgrade.ts
-import { spawnSync } from "child_process";
+import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
-import { basename, dirname, join, relative, resolve } from "path";
-import { fileURLToPath } from "url";
+import { basename, dirname, join, relative, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { defineCommand } from "citty";
-var TEMPLATE_DIR = fileURLToPath(new URL("../templates/default", import.meta.url));
+
+// src/selfUpdate.ts
+import { spawnSync } from "child_process";
+import { resolve, sep } from "path";
+import { fileURLToPath } from "url";
+var PKG = "@apex-stack/core";
+var WIN = process.platform === "win32";
+function latestPublished() {
+  try {
+    const r = spawnSync("npm", ["view", PKG, "version"], {
+      encoding: "utf8",
+      timeout: 4e3,
+      shell: WIN
+    });
+    if (r.status !== 0 || !r.stdout) return null;
+    const v = r.stdout.trim();
+    return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+function isGlobalInstall() {
+  const self = fileURLToPath(import.meta.url);
+  const localRoot = resolve(process.cwd(), "node_modules") + sep;
+  return !self.startsWith(localRoot);
+}
+function installGlobalLatest() {
+  return spawnSync("npm", ["install", "-g", `${PKG}@latest`], { stdio: "inherit", shell: WIN }).status === 0;
+}
+async function maybeSelfUpdate(reexecArgv, choice) {
+  if (choice === false) return false;
+  if (!isGlobalInstall()) return false;
+  const latest = latestPublished();
+  if (!latest || cmpVersion(latest, VERSION) <= 0) return false;
+  const log = console.log;
+  log(
+    `
+  ${color.cyan("\u2191")} A newer Apex CLI is available: ${color.gray(VERSION)} \u2192 ${color.green(latest)}`
+  );
+  const yes = choice ?? (process.stdin.isTTY ? await promptYesNo(`  Update the global CLI now?`) : false);
+  if (!yes) {
+    log(`  ${color.gray("Skipped. Update later with")} ${color.cyan(`npm i -g ${PKG}@latest`)}
+`);
+    return false;
+  }
+  if (!installGlobalLatest()) {
+    log(`  ${color.red("\u2717")} Global update failed \u2014 run ${color.cyan(`npm i -g ${PKG}@latest`)}
+`);
+    return false;
+  }
+  log(`  ${color.green("\u2713")} CLI updated to ${latest} \u2014 re-running on the new engine\u2026
+`);
+  const r = spawnSync("apex", reexecArgv, { stdio: "inherit", shell: WIN });
+  process.exit(r.status ?? 0);
+}
+
+// src/commands/upgrade.ts
+var TEMPLATE_DIR = fileURLToPath2(new URL("../templates/default", import.meta.url));
 var PROTECTED = /* @__PURE__ */ new Set(["package.json"]);
 function projectName(root) {
   try {
@@ -79,10 +138,14 @@ var upgradeCommand = defineCommand({
     vscode: {
       type: "boolean",
       description: "Install the Apex VS Code extension (skip the prompt)"
+    },
+    self: {
+      type: "boolean",
+      description: "Update the global Apex CLI first if a newer one is published (default: ask)"
     }
   },
   async run({ args }) {
-    const root = resolve(process.cwd(), String(args.root));
+    const root = resolve2(process.cwd(), String(args.root));
     const log = console.log;
     if (!existsSync(join(root, "package.json"))) {
       console.error(`
@@ -90,6 +153,15 @@ var upgradeCommand = defineCommand({
 `);
       process.exit(1);
     }
+    const reexecArgv = [
+      "upgrade",
+      String(args.root),
+      ...args.force ? ["--force"] : [],
+      ...args.install === false ? ["--no-install"] : [],
+      ...args.vscode === true ? ["--vscode"] : args.vscode === false ? ["--no-vscode"] : [],
+      "--no-self"
+    ];
+    if (await maybeSelfUpdate(reexecArgv, args.self)) return;
     const name = projectName(root);
     process.stdout.write(banner());
     const added = [];
@@ -141,7 +213,7 @@ var upgradeCommand = defineCommand({
       const pm = detectPm();
       log(`
   ${color.gray(`Installing with ${pm}\u2026`)}`);
-      const ok = spawnSync(pm, ["install"], {
+      const ok = spawnSync2(pm, ["install"], {
         cwd: root,
         stdio: "inherit",
         shell: process.platform === "win32"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-stack/core",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "The full-stack meta-framework for Alpine.js — CLI and runtime",
   "type": "module",
   "license": "MIT",
@@ -47,8 +47,8 @@
     "h3": "^1.13.0",
     "vite": "^6.0.7",
     "zod": "^4.4.3",
-    "@apex-stack/kit": "0.3.0",
-    "@apex-stack/vite": "0.1.7",
+    "@apex-stack/kit": "0.4.0",
+    "@apex-stack/vite": "0.1.8",
     "@apex-stack/theme": "0.3.0"
   },
   "peerDependencies": {

package/templates/default/pages/loading.alpine

@@ -0,0 +1,13 @@
+<!--
+  pages/loading.alpine — the client-side navigation loading boundary.
+
+  Apex renders this once and shows it in the page region during a navigation that
+  takes longer than a moment (e.g. a slow loader). It's plain, presentational
+  HTML — no loader, no interactivity needed.
+-->
+<template x-data>
+  <div class="flex flex-col items-center justify-center gap-3 py-24 text-center">
+    <div class="size-8 animate-spin rounded-full border-2 border-outline border-t-primary dark:border-outline-dark dark:border-t-primary-dark"></div>
+    <p class="text-sm text-on-surface/70 dark:text-on-surface-dark/70">Loading…</p>
+  </div>
+</template>