@nightkatana/kronosys-app 1.0.0-beta.2 → 1.0.0-beta.21

package/app/settings/page.tsx

@@ -35,16 +35,20 @@ import { reportingNav } from "@/lib/reportingStrings";
 import { settingsCopy, type SettingsCopy } from "@/lib/settingsCopy";
 import {
   appShellHeaderClassName,
-  appShellHeaderToolRowClassName,
+  appShellHeaderTitleMetaRowClassName,
+  appShellHeaderToolbarClassName,
 } from "@/lib/appShellHeaderClasses";
+import { AppShellCommandCenterPlaceholder } from "@/components/dashboard/AppShellCommandCenterPlaceholder";
+import { AppShellHeaderSessionMeta } from "@/components/dashboard/AppShellHeaderSessionMeta";
+import { AppShellHeaderWallClock } from "@/components/dashboard/AppShellHeaderWallClock";
 import { workspaceFolderPathStrings } from "@/lib/legacyEditorPayloadKeys";
 import { showWorkspaceFoldersEmptyMessage } from "@/lib/usageProfile";
 import { readDashboardUse24HourClockFromCfg } from "@/lib/dashboardClockFormat";
 import {
   DASHBOARD_TIME_ZONE_SELECT_OPTIONS,
-  isValidIanaTimeZone,
   readDashboardTimeZoneFromCfg,
 } from "@/lib/dashboardTimeZone";
+import { SESSION_NAME_TEMPLATE_CFG_MAX_LEN } from "@/lib/formatSessionNameTemplate";
 import { DEFAULT_WORKSPACE_LOC_EXCLUDED_DIRECTORY_NAMES } from "@/lib/workspaceLocDefaults";
 import { LanguageMenu } from "@/components/dashboard/LanguageMenu";
 import { ScrollToTopFab } from "@/components/dashboard/ScrollToTopFab";
@@ -65,7 +69,7 @@ import {
   writeDashboardColumnHintsDismissed,
 } from "@/lib/dashboardColumnHintsStorage";
 import { KronosysTimePopoverField } from "@/components/dashboard/KronosysTimePopoverField";
-import { Search } from "lucide-react";
+import { FileText, Search } from "lucide-react";
 import { withDashboardSessionParam } from "@/lib/dashboardSessionNav";
 
 type LiveShape = { language?: string };
@@ -102,6 +106,8 @@ type SettingsForm = {
   dashboardDisplayTimeZone: string;
   /** `true` : affichage 24 h ; `false` : 12 h (AM/PM). */
   dashboardUse24HourClock: boolean;
+  /** Gabarit du nom des nouvelles sessions (`%UUID`, strftime POSIX). */
+  dashboardDefaultSessionNameTemplate: string;
   /** Seuil d’alerte (heures) pour la durée murale affichée dans le tableau de bord. */
   dashboardSessionDurationAlertHours: number;
   dashboardShowKronoFocusInHeader: boolean;
@@ -233,6 +239,10 @@ function cfgToForm(cfg: Record<string, unknown> | undefined): SettingsForm {
     dashboardWebUrl: str(cfg?.dashboardWebUrl, "http://kronosys:5555"),
     dashboardDisplayTimeZone: readDashboardTimeZoneFromCfg(cfg),
     dashboardUse24HourClock: readDashboardUse24HourClockFromCfg(cfg),
+    dashboardDefaultSessionNameTemplate: str(
+      cfg?.dashboardDefaultSessionNameTemplate,
+      "",
+    ).slice(0, SESSION_NAME_TEMPLATE_CFG_MAX_LEN),
     dashboardSessionDurationAlertHours: Math.min(
       Math.max(num(cfg?.dashboardSessionDurationAlertHours, 24), 1),
       8760,
@@ -425,8 +435,8 @@ function archivedTaskCount(s: SessionListEntry): number {
     Array.isArray(s.activeTasks) && s.activeTasks.length > 0
       ? s.activeTasks.length
       : s.activeTask
-        ? 1
-        : 0;
+      ? 1
+      : 0;
   return listed + nActive;
 }
 
@@ -514,6 +524,14 @@ function SettingsToc({
     m(s.sectionTagsProjects, "settings-tags-projects") ||
     m(s.tocSubTagsByProject, "settings-tags-by-project");
   const showTagsBlock = showTagsGlobal || showTagsProjects || showTagsByProject;
+  const showTaskTemplates = m(
+    s.sectionTaskTemplates,
+    "settings-task-templates",
+    "template",
+    "modèle",
+    "task template",
+    "gabarit",
+  );
   const showDanger = m(s.sectionDangerZone, "settings-danger-zone");
   const showArchived = m(
     s.sectionArchivedSessions,
@@ -578,7 +596,21 @@ function SettingsToc({
       "settings-session-duration-alert",
       "duration",
     );
-  const showWebBlock = showWebTour || showWebDuration;
+  const showWebDefaultSessionName =
+    m(s.sectionWeb, "settings-web", "dashboard", "api") ||
+    m(
+      s.tocSubDefaultSessionNameTemplate,
+      "settings-default-session-name",
+      "default session",
+      "session name",
+      "%UUID",
+      "strftime",
+      "gabarit",
+      "nom de session",
+    ) ||
+    m(s.dashboardDefaultSessionNameTemplate, "template", "uuid");
+  const showWebBlock =
+    showWebTour || showWebDuration || showWebDefaultSessionName;
   const showLicenses = m(
     s.licensesPageLink,
     "/licenses",
@@ -600,6 +632,7 @@ function SettingsToc({
     showCollection ||
     showHistory ||
     showTagsBlock ||
+    showTaskTemplates ||
     showDanger ||
     showArchived ||
     showExport ||
@@ -615,7 +648,7 @@ function SettingsToc({
   return (
     <nav
       aria-label={s.tocNavAriaLabel}
-      className="rounded-xl border border-zinc-200 bg-zinc-50/90 p-4 dark:border-zinc-800 dark:bg-zinc-900/40"
+      className="rounded-xl border border-zinc-200 bg-zinc-50/90 p-4 lg:max-h-[calc(100dvh-14rem)] lg:overflow-y-scroll lg:overscroll-contain dark:border-zinc-800 dark:bg-zinc-900/40"
     >
       <p className="mb-3 text-xs font-semibold uppercase tracking-wide text-zinc-500 dark:text-zinc-500">
         {s.tocHeading}
@@ -740,6 +773,13 @@ function SettingsToc({
               ) : null}
             </li>
           ) : null}
+          {showTaskTemplates ? (
+            <li>
+              <a href="#settings-task-templates" className={linkClass}>
+                {s.sectionTaskTemplates}
+              </a>
+            </li>
+          ) : null}
           {showGit ? (
             <li>
               <a href="#settings-git" className={linkClass}>
@@ -782,7 +822,7 @@ function SettingsToc({
               <a href="#settings-web" className={linkClass}>
                 {s.sectionWeb}
               </a>
-              {showWebTour || showWebDuration ? (
+              {showWebTour || showWebDuration || showWebDefaultSessionName ? (
                 <ul className={subListClass}>
                   {showWebTour ? (
                     <>
@@ -812,6 +852,16 @@ function SettingsToc({
                       </li>
                     </>
                   ) : null}
+                  {showWebDefaultSessionName ? (
+                    <li>
+                      <a
+                        href="#settings-default-session-name"
+                        className={linkClass}
+                      >
+                        {s.tocSubDefaultSessionNameTemplate}
+                      </a>
+                    </li>
+                  ) : null}
                   {showWebDuration ? (
                     <li>
                       <a
@@ -902,6 +952,10 @@ function SettingsPageContent() {
   >(null);
   const [clearHistoryConfirmOpen, setClearHistoryConfirmOpen] = useState(false);
   const [clearHistoryBusy, setClearHistoryBusy] = useState(false);
+  const [restoreConfirmOpen, setRestoreConfirmOpen] = useState(false);
+  const [restoreBusy, setRestoreBusy] = useState(false);
+  const [restoreFile, setRestoreFile] = useState<File | null>(null);
+  const restoreFileInputRef = useRef<HTMLInputElement | null>(null);
   const [settingsTocFilter, setSettingsTocFilter] = useState("");
   const [settingsTourOpen, setSettingsTourOpen] = useState(false);
 
@@ -1137,8 +1191,8 @@ function SettingsPageContent() {
   const gitlabTokenStatusText = gitlabTokenStoredFlag
     ? s.gitlabTokenStoredYes
     : gitlabTokenFromEnvFlag
-      ? s.gitlabTokenFromEnvYes
-      : s.gitlabTokenNone;
+    ? s.gitlabTokenFromEnvYes
+    : s.gitlabTokenNone;
 
   const headerApiError =
     lang === "fr"
@@ -1507,6 +1561,56 @@ function SettingsPageContent() {
     }
   }, [refresh, router]);
 
+  const restoreBackup = useCallback(async () => {
+    if (!restoreFile) {
+      setSettingsDialogAlert(s.dangerRestoreNoFile);
+      return;
+    }
+    setRestoreBusy(true);
+    try {
+      const fd = new FormData();
+      fd.set("file", restoreFile);
+      const format = restoreFile.name.toLowerCase().endsWith(".json")
+        ? "json"
+        : "sqlite";
+      fd.set("format", format);
+      const res = await fetch("/api/restore", {
+        method: "POST",
+        body: fd,
+      });
+      const text = await res.text();
+      let data: Record<string, unknown> = {};
+      try {
+        data = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+      } catch {
+        data = {};
+      }
+      if (!res.ok || data.ok !== true) {
+        const detail =
+          typeof data.detail === "string"
+            ? data.detail
+            : typeof data.error === "string"
+            ? data.error
+            : text || `HTTP ${res.status}`;
+        setSettingsDialogAlert(
+          `${s.dangerRestoreFailed.replace("{detail}", detail)}`,
+        );
+        return;
+      }
+      setRestoreConfirmOpen(false);
+      setRestoreFile(null);
+      if (restoreFileInputRef.current) {
+        restoreFileInputRef.current.value = "";
+      }
+      await refresh({ preserveForm: false, routerInvalidate: true });
+      setSettingsDialogAlert(
+        format === "json" ? s.dangerRestoreDoneJson : s.dangerRestoreDoneSqlite,
+      );
+    } finally {
+      setRestoreBusy(false);
+    }
+  }, [refresh, restoreFile, s]);
+
   const applyResetToDefaults = useCallback(async () => {
     setResetDefaultsBusy(true);
     setSettingsAck(null);
@@ -1529,7 +1633,7 @@ function SettingsPageContent() {
   return (
     <div className="min-h-screen bg-zinc-100 text-zinc-900 dark:bg-zinc-900 dark:text-zinc-100">
       <header className={appShellHeaderClassName}>
-        <div className={appShellHeaderToolRowClassName}>
+        <div className={appShellHeaderTitleMetaRowClassName}>
           <div className="flex min-w-0 flex-col gap-1">
             <Link
               href={withDashboardSessionParam("/", dashboardSessionNavId)}
@@ -1545,12 +1649,18 @@ function SettingsPageContent() {
               <AppVersionStamp ariaLabelTemplate={dt.appVersionAriaLabel} />
             </p>
           </div>
-          <div className="flex flex-wrap items-center gap-1.5">
+          <AppShellHeaderSessionMeta payload={payload} dt={dt} />
+        </div>
+        <div className="flex w-full justify-end">
+          <div className={appShellHeaderToolbarClassName}>
+            <AppShellHeaderWallClock lang={lang} dt={dt} />
+            <AppShellCommandCenterPlaceholder />
             <AppShellRouteNav
               current="settings"
               labels={nav}
               navAriaLabel={dt.appShellRouteNavAria}
               dashboardSessionId={dashboardSessionNavId}
+              reserveGlobalPauseSlot
             />
             <ThemeToggle lang={lang} />
             <PageRefreshButton
@@ -2656,8 +2766,8 @@ function SettingsPageContent() {
                         gitlabTestFeedback.tone === "ok"
                           ? "mt-2 text-sm text-emerald-600 dark:text-emerald-400"
                           : gitlabTestFeedback.tone === "warn"
-                            ? "mt-2 text-sm text-amber-600 dark:text-amber-400"
-                            : "mt-2 text-sm text-red-600 dark:text-red-400"
+                          ? "mt-2 text-sm text-amber-600 dark:text-amber-400"
+                          : "mt-2 text-sm text-red-600 dark:text-red-400"
                       }
                     >
                       {gitlabTestFeedback.text}
@@ -2773,8 +2883,8 @@ function SettingsPageContent() {
                         {mongoRemoteStatus === "connected"
                           ? s.mongoStatusConnected
                           : mongoRemoteStatus === "failed"
-                            ? s.mongoStatusFailed
-                            : s.mongoStatusPending}
+                          ? s.mongoStatusFailed
+                          : s.mongoStatusPending}
                         {" · "}
                         {mongoUriConfigured ? (
                           <span className="text-emerald-400/90">
@@ -2810,8 +2920,8 @@ function SettingsPageContent() {
                               mongoTestFeedback.tone === "ok"
                                 ? "text-emerald-400"
                                 : mongoTestFeedback.tone === "warn"
-                                  ? "text-amber-400"
-                                  : "text-red-300"
+                                ? "text-amber-400"
+                                : "text-red-300"
                             }`}
                           >
                             {mongoTestFeedback.text}
@@ -3168,6 +3278,36 @@ function SettingsPageContent() {
                       </label>
                     </div>
                   </Field>
+
+                  <div
+                    id="settings-default-session-name"
+                    className="scroll-mt-24"
+                  >
+                    <Field
+                      label={s.dashboardDefaultSessionNameTemplate}
+                      description={s.dashboardDefaultSessionNameTemplateDesc}
+                    >
+                      <input
+                        type="text"
+                        className={inputClass(formLocked)}
+                        value={form.dashboardDefaultSessionNameTemplate}
+                        onChange={(e) =>
+                          update(
+                            "dashboardDefaultSessionNameTemplate",
+                            e.target.value.slice(
+                              0,
+                              SESSION_NAME_TEMPLATE_CFG_MAX_LEN,
+                            ),
+                          )
+                        }
+                        disabled={formLocked}
+                        spellCheck={false}
+                        autoComplete="off"
+                        placeholder="Session %F %UUID"
+                        aria-label={s.dashboardDefaultSessionNameTemplate}
+                      />
+                    </Field>
+                  </div>
                 </div>
                 <div
                   id="settings-dashboard-tour"
@@ -3319,6 +3459,12 @@ function SettingsPageContent() {
                     archivedPageRows.map((sess) => {
                       const label =
                         sess.sessionName?.trim() || sess.sessionId.slice(0, 8);
+                      const noteRaw =
+                        typeof sess.sessionNote === "string"
+                          ? sess.sessionNote.trim()
+                          : "";
+                      const notePreview = noteRaw.replaceAll(/\s+/g, " ");
+                      const hasSessionNote = notePreview.length > 0;
                       const n = archivedTaskCount(sess);
                       const busy = archivedRestoreBusyId === sess.sessionId;
                       return (
@@ -3333,6 +3479,19 @@ function SettingsPageContent() {
                             <div className="text-[0.7rem] text-zinc-500">
                               {n} {sessionTaskCountNoun(n, dt, lang)}
                             </div>
+                            {hasSessionNote ? (
+                              <div
+                                className="mt-1 inline-flex min-w-0 max-w-full items-center gap-1 text-[0.7rem] text-zinc-500"
+                                title={notePreview}
+                              >
+                                <FileText
+                                  size={12}
+                                  className="shrink-0"
+                                  aria-hidden
+                                />
+                                <span className="truncate">{notePreview}</span>
+                              </div>
+                            ) : null}
                           </div>
                           <button
                             type="button"
@@ -3406,6 +3565,64 @@ function SettingsPageContent() {
                   {s.sectionDangerZone}
                 </h2>
                 <div className="max-w-xl rounded-xl border border-red-300/90 bg-red-50/80 p-4 dark:border-red-900/55 dark:bg-red-950/30">
+                  <h3 className="text-sm font-semibold text-red-900 dark:text-red-200">
+                    {s.dangerBackupRestoreTitle}
+                  </h3>
+                  <p className="mt-2 text-xs leading-relaxed text-red-900/85 dark:text-red-200/85">
+                    {s.dangerBackupRestoreIntro}
+                  </p>
+                  <div className="mt-3 flex flex-wrap gap-2">
+                    <a
+                      href="/api/backup?format=json"
+                      download
+                      className="rounded-lg border border-red-500/70 px-3 py-1.5 text-xs font-medium text-red-900 hover:bg-red-100 dark:text-red-200 dark:hover:bg-red-900/40"
+                    >
+                      {s.dangerClearHistoryBackupJson}
+                    </a>
+                    <a
+                      href="/api/backup?format=csv-zip"
+                      download
+                      className="rounded-lg border border-red-500/70 px-3 py-1.5 text-xs font-medium text-red-900 hover:bg-red-100 dark:text-red-200 dark:hover:bg-red-900/40"
+                    >
+                      {s.dangerClearHistoryBackupCsvZip}
+                    </a>
+                    <a
+                      href="/api/backup?format=sqlite"
+                      download
+                      className="rounded-lg border border-red-500/70 px-3 py-1.5 text-xs font-medium text-red-900 hover:bg-red-100 dark:text-red-200 dark:hover:bg-red-900/40"
+                    >
+                      {s.dangerClearHistoryBackupSqlite}
+                    </a>
+                  </div>
+                  <div className="mt-4 space-y-2">
+                    <label className="block text-xs font-medium text-red-900/90 dark:text-red-200/90">
+                      {s.dangerRestorePickFile}
+                    </label>
+                    <input
+                      ref={restoreFileInputRef}
+                      type="file"
+                      accept=".json,.sqlite,.db,application/json,application/vnd.sqlite3"
+                      disabled={restoreBusy || clearHistoryBusy}
+                      className="block w-full rounded-lg border border-red-300 bg-white px-3 py-2 text-xs text-zinc-800 file:mr-3 file:rounded file:border-0 file:bg-red-100 file:px-2.5 file:py-1 file:text-xs file:font-medium file:text-red-900 dark:border-red-900/60 dark:bg-zinc-950 dark:text-zinc-200 dark:file:bg-red-900/35 dark:file:text-red-200"
+                      onChange={(e) => {
+                        const f = e.target.files?.[0] ?? null;
+                        setRestoreFile(f);
+                      }}
+                    />
+                    <p className="text-[11px] leading-relaxed text-red-900/80 dark:text-red-300/80">
+                      {s.dangerRestoreHint}
+                    </p>
+                    <button
+                      type="button"
+                      disabled={!restoreFile || restoreBusy || clearHistoryBusy}
+                      className="rounded-lg border border-red-600/80 bg-red-700 px-3 py-1.5 text-xs font-medium text-white hover:bg-red-600 disabled:cursor-not-allowed disabled:opacity-50 dark:border-red-500 dark:bg-red-800/90 dark:hover:bg-red-700"
+                      onClick={() => setRestoreConfirmOpen(true)}
+                    >
+                      {restoreBusy
+                        ? s.dangerRestoreBusy
+                        : s.dangerRestoreButton}
+                    </button>
+                  </div>
                   <h3 className="text-sm font-semibold text-red-900 dark:text-red-200">
                     {s.dangerClearHistoryTitle}
                   </h3>
@@ -3450,6 +3667,23 @@ function SettingsPageContent() {
         onCancel={() => setMongoResyncConfirmOpen(false)}
         onConfirm={() => void executeMongoResync()}
       />
+      <DashboardConfirmModal
+        open={restoreConfirmOpen}
+        title={s.dangerRestoreButton}
+        message={s.dangerRestoreConfirm}
+        cancelLabel={s.dialogCancelBtn}
+        confirmLabel={s.dialogConfirmBtn}
+        confirmVariant="danger"
+        pending={restoreBusy}
+        onCancel={() => {
+          if (!restoreBusy) {
+            setRestoreConfirmOpen(false);
+          }
+        }}
+        onConfirm={() => {
+          void restoreBackup();
+        }}
+      />
       <DashboardConfirmModal
         open={clearHistoryConfirmOpen}
         title={s.dangerClearHistoryTitle}

package/bin/kronosys.mjs

@@ -5,21 +5,49 @@
  * Supported commands:
  *   start   -> next start -p 5555 (production, default; auto-build if needed)
  *   dev     -> next dev --webpack -H kronosys -p 5555
+ *   --version, -v, version -> print installed Kronosys version
  */
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const projectRoot = resolve(__dirname, "..");
+const packageJson = JSON.parse(
+  readFileSync(resolve(projectRoot, "package.json"), "utf8"),
+);
+const packageVersion = packageJson.version;
+const inNodeModules =
+  projectRoot.includes("/node_modules/") ||
+  projectRoot.includes("\\node_modules\\");
+const isWindows = process.platform === "win32";
+const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+const npxBin = process.platform === "win32" ? "npx.cmd" : "npx";
+const psBin = process.platform === "win32" ? "powershell.exe" : null;
 
 const [, , command = "start", ...rest] = process.argv;
 
+if (command === "--version" || command === "-v" || command === "version") {
+  console.log(packageVersion);
+  process.exit(0);
+}
+
 const commands = {
-  start: ["npx", "next", "start", "-p", "5555", ...rest],
-  dev: ["npx", "next", "dev", "--webpack", "-H", "kronosys", "-p", "5555", ...rest],
+  start: [npxBin, "next", "start", "-p", "5555", ...rest],
+  dev: [
+    npxBin,
+    "next",
+    "dev",
+    "--webpack",
+    "-H",
+    "kronosys",
+    "-p",
+    "5555",
+    ...rest,
+  ],
 };
 
 if (!commands[command]) {
@@ -28,14 +56,34 @@ if (!commands[command]) {
   process.exit(1);
 }
 
-function runCommand(bin, args, env) {
+function runCommand(bin, args, env, cwd) {
   return new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(bin, args, {
-      cwd: projectRoot,
-      stdio: "inherit",
-      shell: false,
-      env,
-    });
+    const windowsArg = (arg) => `'${String(arg).replaceAll("'", "''")}'`;
+
+    const child = isWindows
+      ? spawn(
+          psBin,
+          [
+            "-NoLogo",
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            "& " + [bin, ...args].map(windowsArg).join(" "),
+          ],
+          {
+            cwd,
+            stdio: "inherit",
+            shell: false,
+            env,
+          },
+        )
+      : spawn(bin, args, {
+          cwd,
+          stdio: "inherit",
+          shell: false,
+          env,
+        });
 
     child.on("error", (err) => {
       rejectPromise(err);
@@ -47,23 +95,100 @@ function runCommand(bin, args, env) {
   });
 }
 
+function prepareRuntimeRoot() {
+  const runtimeRoot = resolve(
+    homedir(),
+    ".kronosys",
+    "runtime",
+    String(packageVersion),
+  );
+  const runtimePackageJson = resolve(runtimeRoot, "package.json");
+
+  if (!existsSync(runtimePackageJson)) {
+    mkdirSync(runtimeRoot, { recursive: true });
+    cpSync(projectRoot, runtimeRoot, {
+      recursive: true,
+      force: true,
+      filter: (src) => {
+        const normalized = src.replaceAll("\\", "/");
+        const rel = normalized
+          .replace(projectRoot.replaceAll("\\", "/"), "")
+          .replace(/^\/+/, "");
+        if (!rel) return true;
+        if (rel === ".next" || rel.startsWith(".next/")) return false;
+        if (rel === "node_modules" || rel.startsWith("node_modules/"))
+          return false;
+        return true;
+      },
+    });
+  }
+
+  return runtimeRoot;
+}
+
 async function main() {
+  const runRoot = inNodeModules ? prepareRuntimeRoot() : projectRoot;
   const env = {
     ...process.env,
     NODE_ENV: command === "dev" ? "development" : "production",
   };
 
-  // Production mode requires a Next build. For global installs, build once automatically.
-  if (command === "start" && !existsSync(resolve(projectRoot, ".next", "BUILD_ID"))) {
-    console.log("[kronosys] No production build found. Running `next build`...");
-    const buildCode = await runCommand("npx", ["next", "build", "--webpack"], env);
+  // Global installs live under node_modules; install runtime deps in copied runtime dir.
+  if (inNodeModules && !existsSync(resolve(runRoot, "node_modules"))) {
+    console.log("[kronosys] Installing runtime dependencies...");
+    const installCode = await runCommand(
+      npmBin,
+      ["install", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund"],
+      {
+        ...env,
+        HUSKY: "0",
+        npm_config_cache:
+          process.env.npm_config_cache ?? resolve(homedir(), ".npm"),
+      },
+      runRoot,
+    );
+    if (installCode !== 0) {
+      process.exit(installCode);
+    }
+
+    // Ensure native bindings are present for the current OS/ABI.
+    const rebuildCode = await runCommand(
+      npmBin,
+      ["rebuild", "better-sqlite3", "--no-audit", "--no-fund"],
+      {
+        ...env,
+        HUSKY: "0",
+        npm_config_cache:
+          process.env.npm_config_cache ?? resolve(homedir(), ".npm"),
+      },
+      runRoot,
+    );
+    if (rebuildCode !== 0) {
+      process.exit(rebuildCode);
+    }
+  }
+
+  // Production mode requires a Next build. Build once on first run.
+  if (
+    command === "start" &&
+    !existsSync(resolve(runRoot, ".next", "BUILD_ID"))
+  ) {
+    console.log(
+      "[kronosys] No production build found. Running `next build`...",
+    );
+    const buildCode = await runCommand(
+      npxBin,
+      ["next", "build", "--webpack"],
+      env,
+      runRoot,
+    );
     if (buildCode !== 0) {
       process.exit(buildCode);
     }
   }
 
   const [bin, ...args] = commands[command];
-  const code = await runCommand(bin, args, env);
+  const code = await runCommand(bin, args, env, runRoot);
   process.exit(code);
 }
 

package/components/KronosysPayloadProvider.tsx

@@ -53,6 +53,8 @@ export function KronosysPayloadProvider({ children }: { children: ReactNode }) {
         return true;
       } catch (e: unknown) {
         lastRefreshOkRef.current = false;
+        latestPayloadRef.current = null;
+        setPayload(null);
         setError(e instanceof Error ? e.message : String(e));
         return false;
       }

package/components/RouteTransition.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { usePathname } from "next/navigation";
+
+type Props = Readonly<{
+  children: ReactNode;
+}>;
+
+export function RouteTransition({ children }: Props) {
+  const pathname = usePathname();
+
+  return (
+    <div key={pathname} className="kronosys-route-transition-in">
+      {children}
+    </div>
+  );
+}