paneltir 0.6.0 → 0.8.0

package/INSTALL.md

@@ -19,7 +19,7 @@ identity** — never another project's.
    npm install paneltir
 
    # or, without npm access, straight from the repository:
-   # npm install github:daifukus/paneltir#v0.6.0
+   # npm install github:daifukus/paneltir#v0.8.0
    ```
 
    (Use the tag you were given; never install without pinning a version.)
@@ -181,7 +181,7 @@ identity** — never another project's.
 
    ```bash
    npx paneltir version          # version, fingerprint, where it came from
-   npx paneltir check 0.6.0      # exits non-zero if that is not what is installed
+   npx paneltir check 0.8.0      # exits non-zero if that is not what is installed
    npx paneltir board            # read the board and say what is wrong with it
    ```
 

package/README.md

@@ -54,7 +54,7 @@ tag rather than a branch, so an unfinished push cannot reach a project:
 npm install paneltir
 
 # or, without npm access, straight from the repository:
-# npm install github:daifukus/paneltir#v0.6.0
+# npm install github:daifukus/paneltir#v0.8.0
 ```
 
 Installing from Git runs the `prepare` script, which builds `dist/`, so the

package/bin/paneltir.mjs

@@ -239,7 +239,12 @@ function version() {
   console.log(`paneltir v${pkg.version}`)
   console.log(`fingerprint ${fingerprint.hash}`)
   console.log(`${fingerprint.fileCount} tracked files`)
-  console.log(`installed from github:daifukus/paneltir#v${pkg.version}`)
+  // It used to print "installed from github:daifukus/paneltir#vX.Y.Z", which
+  // was true while that was the only way in and became a guess the moment the
+  // package went to npm. A copy on disk does not carry where it was fetched
+  // from — npm records that in the consumer's lockfile, not here — so the
+  // line is gone rather than wrong. The version and the fingerprint are facts;
+  // that was not one.
 }
 
 /**

package/dist/index.d.ts

@@ -872,6 +872,14 @@ interface Preferences {
     seen?: string[];
     /** Ids of guide notes already dismissed. */
     guideDismissed?: string[];
+    /**
+     * Whether an update card is written as an order rather than a suggestion.
+     *
+     * It does not make anything automatic — the panel cannot run npm, and this
+     * changes `order` on the card it offers to write, nothing else. Off means
+     * the card asks; on means it tells.
+     */
+    updateAsOrder?: boolean;
 }
 interface PanelState {
     v: 2;
@@ -1115,6 +1123,21 @@ interface UiStrings {
     all: string;
     board: string;
     analysis: string;
+    /** The Revisions tab. Short, because it sits beside Board and Analysis. */
+    history: string;
+    updateTitle: string;
+    updateSubtitle: string;
+    updateCurrent: (version: string) => string;
+    updateAvailable: (version: string) => string;
+    updateUpToDate: string;
+    updateUnknown: string;
+    updateCreateCard: string;
+    updateCardExists: string;
+    updateAsOrder: string;
+    updateAsOrderHow: string;
+    notifUpdate: string;
+    updateCardTitle: (version: string) => string;
+    updateCardBody: (version: string) => string;
     cardDetail: string;
     panelSettings: string;
     title: string;
@@ -1417,6 +1440,14 @@ interface PanelAppProps {
     showLanguage?: boolean;
     /** The revision log: one entry per session, newest first. */
     showHistory?: boolean;
+    /**
+     * Ask the public npm registry whether a newer kit has been published.
+     *
+     * Opt-in, because it is a request leaving the reader's browser and that is
+     * the caller's decision rather than the kit's. Nothing is installed either
+     * way: the panel offers to write a card, and a session acts on it.
+     */
+    checkForUpdates?: boolean;
     /** Endpoint that commits the board back to the repository, when there is one. */
     saveEndpoint?: string;
     /**
@@ -1434,7 +1465,7 @@ interface PanelAppProps {
         fileCount: number;
     };
 }
-declare function PanelApp({ state: initialState, themes, defaultTheme, brand, decoration, className, footer, links, capabilities, extras, showLanguage, showHistory, saveEndpoint, marketplaceEndpoint, marketplaceReport, fingerprint, }: PanelAppProps): React.JSX.Element;
+declare function PanelApp({ state: initialState, themes, defaultTheme, brand, decoration, className, footer, links, capabilities, extras, showLanguage, showHistory, checkForUpdates, saveEndpoint, marketplaceEndpoint, marketplaceReport, fingerprint, }: PanelAppProps): React.JSX.Element;
 
 /**
  * Applies a board move to the flat card list.

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/version.ts
-var PANELTIR_VERSION = "0.6.0";
-var PANELTIR_FINGERPRINT = "sha256:cb1a1df3cac0d3cc775fbaa7b9f385d6d35e22cecbe86cc0a1da4338cf43de37";
-var PANELTIR_FILE_COUNT = 151;
+var PANELTIR_VERSION = "0.8.0";
+var PANELTIR_FINGERPRINT = "sha256:a252ef2a015240e0e8463c0ebb0ef7a8af80ad7ade66f2c48e71657500d506d5";
+var PANELTIR_FILE_COUNT = 153;
 var paneltirBuild = {
   version: PANELTIR_VERSION,
   fingerprint: PANELTIR_FINGERPRINT,
@@ -1302,6 +1302,37 @@ function isCard(value) {
 // src/panel/PanelApp.tsx
 import React12, { useCallback as useCallback5, useEffect as useEffect9, useMemo as useMemo5, useState as useState9 } from "react";
 
+// src/panel/updates.ts
+var REGISTRY_URL = "https://registry.npmjs.org/paneltir/latest";
+function isNewer(candidate, current) {
+  const parts = (value) => value.trim().replace(/^v/, "").split(/[-+]/)[0].split(".").map((piece) => Number.parseInt(piece, 10));
+  const left = parts(candidate);
+  const right = parts(current);
+  if (left.some(Number.isNaN) || right.some(Number.isNaN)) return false;
+  for (let i = 0; i < 3; i += 1) {
+    const a = left[i] ?? 0;
+    const b = right[i] ?? 0;
+    if (a !== b) return a > b;
+  }
+  return false;
+}
+async function checkForUpdate(current, fetchImpl = fetch) {
+  try {
+    const response = await fetchImpl(REGISTRY_URL, { headers: { accept: "application/json" } });
+    if (!response.ok) return null;
+    const body = await response.json();
+    const latest = typeof body.version === "string" ? body.version : null;
+    if (!latest) return null;
+    return { current, latest, behind: isNewer(latest, current) };
+  } catch {
+    return null;
+  }
+}
+function updateCardId(version) {
+  const found = /\d+\.\d+\.\d+/.exec(version);
+  return `paneltir-update-${found ? found[0] : "unknown"}`;
+}
+
 // src/panel/themes.ts
 var PRESET_FORM = {
   midnight: THEME_FORMS.panel,
@@ -1355,6 +1386,20 @@ var UI = {
     all: "All",
     board: "Board",
     analysis: "Analysis",
+    history: "Revisions",
+    updateTitle: "The kit this panel runs on",
+    updateSubtitle: "What is installed, and what has been published since.",
+    updateCurrent: (version) => `Installed: v${version}`,
+    updateAvailable: (version) => `v${version} has been published.`,
+    updateUpToDate: "This is the newest published version.",
+    updateUnknown: "The registry could not be reached, so there is nothing to report either way.",
+    updateCreateCard: "Add a card asking for it",
+    updateCardExists: "The board already carries a card for this version.",
+    updateAsOrder: "Write it as an order, not a suggestion",
+    updateAsOrderHow: "This does not update anything on its own \u2014 the panel cannot run npm. It decides whether the card it writes asks for the update or instructs it.",
+    notifUpdate: "A newer Paneltir has been published",
+    updateCardTitle: (version) => `Update Paneltir to v${version}`,
+    updateCardBody: (version) => `Run \`npm install paneltir@${version}\` in this project, then check the panel still builds and renders. The version in use is reported by \`paneltirBuild\`, so it can be confirmed rather than assumed.`,
     cardDetail: "Card",
     panelSettings: "Panel settings",
     title: "Title",
@@ -1615,6 +1660,20 @@ var UI = {
     all: "Todo",
     board: "Tablero",
     analysis: "An\xE1lisis",
+    history: "Revisiones",
+    updateTitle: "El kit sobre el que corre este panel",
+    updateSubtitle: "Qu\xE9 hay instalado, y qu\xE9 se ha publicado desde entonces.",
+    updateCurrent: (version) => `Instalada: v${version}`,
+    updateAvailable: (version) => `Se ha publicado la v${version}.`,
+    updateUpToDate: "Esta es la versi\xF3n publicada m\xE1s reciente.",
+    updateUnknown: "No se pudo consultar el registro, as\xED que no hay nada que decir en ning\xFAn sentido.",
+    updateCreateCard: "A\xF1adir una tarjeta pidi\xE9ndolo",
+    updateCardExists: "El tablero ya lleva una tarjeta para esta versi\xF3n.",
+    updateAsOrder: "Escribirla como orden, no como sugerencia",
+    updateAsOrderHow: "Esto no actualiza nada por su cuenta \u2014 el panel no puede ejecutar npm. Decide si la tarjeta que escribe pide la actualizaci\xF3n o la manda.",
+    notifUpdate: "Se ha publicado un Paneltir m\xE1s nuevo",
+    updateCardTitle: (version) => `Actualizar Paneltir a la v${version}`,
+    updateCardBody: (version) => `Ejecuta \`npm install paneltir@${version}\` en este proyecto y comprueba que el panel sigue construy\xE9ndose y dibuj\xE1ndose. La versi\xF3n en uso la reporta \`paneltirBuild\`, as\xED que se puede confirmar en vez de darla por hecha.`,
     cardDetail: "Tarjeta",
     panelSettings: "Ajustes del panel",
     title: "T\xEDtulo",
@@ -2651,6 +2710,20 @@ function applyMove(cards, move, visible) {
 // src/panel/PanelApp.tsx
 import { Fragment as Fragment5, jsx as jsx19, jsxs as jsxs17 } from "react/jsx-runtime";
 var IMPORTED = "imported";
+function parseJson(body) {
+  try {
+    const parsed = JSON.parse(body);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function saveError(status, data, body) {
+  if (typeof data.error === "string" && data.error) return data.error;
+  const code = body.match(/\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/)?.[0];
+  const id = body.match(/\bID:\s*([\w:.-]+)/i)?.[1];
+  return [`HTTP ${status}`, code, id && `id ${id}`].filter(Boolean).join(" \u2014 ");
+}
 var PRIORITY_TONE = {
   high: "danger",
   medium: "warning",
@@ -2669,6 +2742,7 @@ function PanelApp({
   extras,
   showLanguage,
   showHistory,
+  checkForUpdates,
   saveEndpoint,
   marketplaceEndpoint,
   marketplaceReport,
@@ -2686,6 +2760,7 @@ function PanelApp({
   const [filter, setFilter] = useState9("all");
   const [openCardId, setOpenCardId] = useState9(null);
   const [settingsOpen, setSettingsOpen] = useState9(false);
+  const [update, setUpdate] = useState9(null);
   const [helpOpen, setHelpOpen] = useState9(false);
   const [setup, setSetup] = useState9(null);
   const [signOut, setSignOut] = useState9("idle");
@@ -2794,6 +2869,15 @@ function PanelApp({
         onOpen: () => setOpenCardId(card.id)
       });
     }
+    if (update?.behind && !state.cards.some((card) => card.id === updateCardId(update.latest))) {
+      items.push({
+        id: `paneltir-update:${update.latest}`,
+        tone: "info",
+        title: ui.notifUpdate,
+        detail: ui.updateAvailable(update.latest),
+        onOpen: () => setSettingsOpen(true)
+      });
+    }
     if (state.importedTheme?.refreshRequested) {
       items.push({
         id: `theme-refresh:${state.importedTheme.refreshRequested}`,
@@ -2873,6 +2957,23 @@ function PanelApp({
     },
     [state.areas]
   );
+  const addUpdateCard = useCallback5(() => {
+    if (!update?.behind) return;
+    const id = updateCardId(update.latest);
+    if (state.cards.some((card2) => card2.id === id)) return;
+    const card = {
+      ...emptyCard("next", state.areas[0]?.id ?? "general"),
+      id,
+      title: { en: UI.en.updateCardTitle(update.latest), es: UI.es.updateCardTitle(update.latest) },
+      body: { en: UI.en.updateCardBody(update.latest), es: UI.es.updateCardBody(update.latest) },
+      priority: "medium",
+      risk: "low",
+      owner: "claude",
+      order: state.preferences?.updateAsOrder === true
+    };
+    setState((current) => ({ ...current, updatedAt: today(), cards: [...current.cards, card] }));
+    setOpenCardId(id);
+  }, [update, state.cards, state.areas, state.preferences?.updateAsOrder]);
   const moveCard = useCallback5(
     (move) => {
       setState((current) => {
@@ -2992,6 +3093,16 @@ function PanelApp({
     setMarketAsked(true);
     loadMarketplace(false);
   }, [view, marketAsked, marketplaceEndpoint, loadMarketplace]);
+  useEffect9(() => {
+    if (!checkForUpdates || !fingerprint?.version) return;
+    let cancelled = false;
+    void checkForUpdate(fingerprint.version).then((status2) => {
+      if (!cancelled) setUpdate(status2);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [checkForUpdates, fingerprint?.version]);
   useEffect9(() => {
     if (!helpOpen || !saveEndpoint || setup) return;
     let cancelled = false;
@@ -3025,10 +3136,11 @@ function PanelApp({
         credentials: "same-origin",
         body: JSON.stringify({ state: next, message: "chore(panel): update the board from the panel" })
       });
-      const data = await response.json().catch(() => ({}));
+      const body = await response.text().catch(() => "");
+      const data = parseJson(body);
       if (!response.ok) {
         const conflict = response.status === 409;
-        throw Object.assign(new Error(data.error || `HTTP ${response.status}`), { conflict });
+        throw Object.assign(new Error(saveError(response.status, data, body)), { conflict });
       }
       setSavedSnapshot(JSON.stringify(state));
       setSave({
@@ -3078,7 +3190,7 @@ function PanelApp({
         ),
         status,
         controls: /* @__PURE__ */ jsxs17(Fragment5, { children: [
-          (initialState.analysis || hasMarketplace) && /* @__PURE__ */ jsxs17("span", { className: "pt-views", children: [
+          (initialState.analysis || hasMarketplace || showHistory) && /* @__PURE__ */ jsxs17("span", { className: "pt-views", children: [
             /* @__PURE__ */ jsx19(
               "button",
               {
@@ -3108,6 +3220,16 @@ function PanelApp({
                 onClick: () => setView("marketplace"),
                 children: ui.marketplace
               }
+            ),
+            showHistory && /* @__PURE__ */ jsx19(
+              "button",
+              {
+                type: "button",
+                className: `pt-lang${view === "history" ? " is-on" : ""}`,
+                "aria-pressed": view === "history",
+                onClick: () => setView("history"),
+                children: ui.history
+              }
             )
           ] }),
           showLanguage && LANGS.map((code) => /* @__PURE__ */ jsx19(
@@ -3335,33 +3457,6 @@ function PanelApp({
           )
         }
       ),
-      showHistory && /* @__PURE__ */ jsxs17("section", { className: "pt-panel-page pt-panel-section", id: "revisions", children: [
-        /* @__PURE__ */ jsxs17("div", { children: [
-          /* @__PURE__ */ jsx19("p", { className: "pt-eyebrow", children: ui.historyEyebrow }),
-          /* @__PURE__ */ jsx19("h2", { className: "pt-h2", children: ui.historyTitle }),
-          /* @__PURE__ */ jsx19("p", { className: "pt-sub", children: ui.historyIntro })
-        ] }),
-        state.runs.length === 0 ? /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", children: ui.historyEmpty }) : /* @__PURE__ */ jsx19("ol", { className: "pt-runs", children: [...state.runs].reverse().map((run) => /* @__PURE__ */ jsxs17("li", { className: "pt-run pt-hud", children: [
-          /* @__PURE__ */ jsxs17("p", { className: "pt-run__meta", children: [
-            run.date,
-            " \xB7 ",
-            run.by === "claude" ? "Claude" : ui.ownerYou,
-            run.fingerprint ? ` \xB7 ${run.fingerprint.replace("sha256:", "").slice(0, 12)}` : ""
-          ] }),
-          /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", children: t(run.summary) }),
-          run.cards.length > 0 && /* @__PURE__ */ jsxs17("p", { className: "pt-run__cards", children: [
-            /* @__PURE__ */ jsxs17("span", { children: [
-              ui.historyTouched,
-              ":"
-            ] }),
-            " ",
-            run.cards.map((id) => {
-              const card = state.cards.find((candidate) => candidate.id === id);
-              return card ? t(card.title) || ui.untitled : id;
-            }).join(" \xB7 ")
-          ] })
-        ] }, run.id)) })
-      ] }),
       extras,
       capabilities && capabilities.length > 0 && /* @__PURE__ */ jsxs17("section", { className: "pt-panel-page pt-panel-section", id: "functions", children: [
         /* @__PURE__ */ jsxs17("div", { children: [
@@ -3380,6 +3475,33 @@ function PanelApp({
         ] }, capability.id)) })
       ] })
     ] }),
+    view === "history" && showHistory && /* @__PURE__ */ jsxs17("section", { className: "pt-panel-page pt-panel-section", id: "revisions", children: [
+      /* @__PURE__ */ jsxs17("div", { children: [
+        /* @__PURE__ */ jsx19("p", { className: "pt-eyebrow", children: ui.historyEyebrow }),
+        /* @__PURE__ */ jsx19("h2", { className: "pt-h2", children: ui.historyTitle }),
+        /* @__PURE__ */ jsx19("p", { className: "pt-sub", children: ui.historyIntro })
+      ] }),
+      state.runs.length === 0 ? /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", children: ui.historyEmpty }) : /* @__PURE__ */ jsx19("ol", { className: "pt-runs", children: [...state.runs].reverse().map((run) => /* @__PURE__ */ jsxs17("li", { className: "pt-run pt-hud", children: [
+        /* @__PURE__ */ jsxs17("p", { className: "pt-run__meta", children: [
+          run.date,
+          " \xB7 ",
+          run.by === "claude" ? "Claude" : ui.ownerYou,
+          run.fingerprint ? ` \xB7 ${run.fingerprint.replace("sha256:", "").slice(0, 12)}` : ""
+        ] }),
+        /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", children: t(run.summary) }),
+        run.cards.length > 0 && /* @__PURE__ */ jsxs17("p", { className: "pt-run__cards", children: [
+          /* @__PURE__ */ jsxs17("span", { children: [
+            ui.historyTouched,
+            ":"
+          ] }),
+          " ",
+          run.cards.map((id) => {
+            const card = state.cards.find((candidate) => candidate.id === id);
+            return card ? t(card.title) || ui.untitled : id;
+          }).join(" \xB7 ")
+        ] })
+      ] }, run.id)) })
+    ] }),
     /* @__PURE__ */ jsx19(
       CardSheet,
       {
@@ -3485,6 +3607,23 @@ function PanelApp({
           /* @__PURE__ */ jsx19("p", { className: "pt-marketplace__detail", children: ui.importedRefreshHow })
         ] })
       ] }),
+      checkForUpdates && fingerprint?.version && /* @__PURE__ */ jsxs17(DetailSection, { title: ui.updateTitle, subtitle: ui.updateSubtitle, children: [
+        /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", children: ui.updateCurrent(fingerprint.version) }),
+        /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", style: { marginTop: 8 }, children: !update ? ui.updateUnknown : update.behind ? ui.updateAvailable(update.latest) : ui.updateUpToDate }),
+        update?.behind && (state.cards.some((card) => card.id === updateCardId(update.latest)) ? /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", style: { marginTop: 8 }, children: ui.updateCardExists }) : /* @__PURE__ */ jsx19("div", { className: "pt-panel-row", style: { marginTop: 12 }, children: /* @__PURE__ */ jsx19("button", { type: "button", className: "pt-btn", onClick: addUpdateCard, children: ui.updateCreateCard }) })),
+        /* @__PURE__ */ jsxs17("label", { className: "pt-panel-row", style: { marginTop: 12 }, children: [
+          /* @__PURE__ */ jsx19(
+            "input",
+            {
+              type: "checkbox",
+              checked: state.preferences?.updateAsOrder === true,
+              onChange: (event) => setPreference("updateAsOrder", event.target.checked)
+            }
+          ),
+          /* @__PURE__ */ jsx19("span", { className: "pt-panel-text", children: ui.updateAsOrder })
+        ] }),
+        /* @__PURE__ */ jsx19("p", { className: "pt-marketplace__detail", children: ui.updateAsOrderHow })
+      ] }),
       fingerprint && /* @__PURE__ */ jsxs17(DetailSection, { title: ui.fingerprint, subtitle: ui.fingerprintSubtitle, children: [
         /* @__PURE__ */ jsx19("p", { className: "pt-panel-mono", children: fingerprint.hash }),
         /* @__PURE__ */ jsx19("p", { className: "pt-panel-text", style: { marginTop: 8 }, children: ui.trackedFiles(fingerprint.fileCount, fingerprint.version) })

package/fingerprint.json

@@ -1,7 +1,7 @@
 {
   "name": "paneltir",
-  "version": "0.6.0",
-  "hash": "sha256:cb1a1df3cac0d3cc775fbaa7b9f385d6d35e22cecbe86cc0a1da4338cf43de37",
-  "fileCount": 151,
-  "generatedAt": "2026-09-06T10:08:28.981Z"
+  "version": "0.8.0",
+  "hash": "sha256:a252ef2a015240e0e8463c0ebb0ef7a8af80ad7ade66f2c48e71657500d506d5",
+  "fileCount": 153,
+  "generatedAt": "2026-09-07T12:59:14.850Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paneltir",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A React UI kit for admin panels: page frame, a board with touch-ready drag and drop, detail sheets, and a whole panel in one component. Structure and behaviour are fixed; colour and brand belong to each project.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "DFKlabs (https://DFKlabs.com)",
@@ -64,7 +64,7 @@
     "check:boards": "node scripts/check-boards.mjs",
     "demo:install": "npm --prefix examples/demo ci",
     "demo:build": "npm --prefix examples/demo run build",
-    "verify": "npm run typecheck && npm run build && npm run icons:check && npm run seo:check && npm run test:auth && npm run test:marketplace && npm run test:init && npm run test:board && npm run check:boards && npm run check:docs && npm run check:package && npm run fingerprint:check",
+    "verify": "npm run typecheck && npm run build && npm run icons:check && npm run seo:check && npm run test:auth && npm run test:marketplace && npm run test:init && npm run test:board && npm run test:updates && npm run check:boards && npm run check:docs && npm run check:package && npm run fingerprint:check",
     "site:install": "npm --prefix site ci",
     "site:dev": "npm --prefix site run dev",
     "site:build": "npm --prefix site run build",
@@ -72,6 +72,7 @@
     "check:docs": "node scripts/check-docs.mjs",
     "check:package": "node scripts/check-package.mjs",
     "test:init": "node scripts/test-init.mjs",
+    "test:updates": "node scripts/test-updates.mjs",
     "test:board": "node scripts/test-board.mjs"
   },
   "peerDependencies": {

package/template/api/panel-state.ts

@@ -24,7 +24,98 @@
  *   PANEL_FILE      optional path to the board within it.
  *   PANEL_BRANCH    optional, defaults to main.
  */
-import { SESSION_COOKIE, readCookie, verifyToken } from '../lib/session'
+/**
+ * The session check, carried here rather than imported.
+ *
+ * This is the rule `middleware.ts` lives by, and it reached the functions the
+ * hard way: every function under `api/` that imported anything answered
+ * FUNCTION_INVOCATION_FAILED on every request, while the middleware, which
+ * imports nothing, never failed once. A wrapper added to catch and name the
+ * fault changed nothing, which is the answer — the module never runs, so there
+ * is no handler for a `try` to protect.
+ *
+ * It is a copy of `lib/session.ts`, and `npm run test:auth` holds every copy to
+ * the same answer over the same tokens. Edit this file freely; if you change
+ * the check, change it everywhere the test names.
+ */
+const SESSION_COOKIE = 'pt_session'
+const VERSION = 'v1'
+
+/**
+ * Reads one variable, surviving a runtime with no `process` at all.
+ *
+ * Written out as literal `process.env.X` accesses because that is the form
+ * build tools substitute at build time; a computed key would leave nothing to
+ * substitute. A bare access is a ReferenceError where `process` is undefined,
+ * which in middleware reads as the whole route crashing rather than as a
+ * missing variable — hence the catch.
+ */
+function env(name: 'ADMIN_PASSWORD' | 'SESSION_SECRET'): string | undefined {
+  try {
+    if (name === 'ADMIN_PASSWORD') return process.env.ADMIN_PASSWORD || undefined
+    return process.env.SESSION_SECRET || undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Kept identical to lib/session.ts; test:auth asserts they agree. */
+function signingSecret(): string | null {
+  const password = env('ADMIN_PASSWORD')
+  if (!password) return null
+  return env('SESSION_SECRET') || password
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const encoder = new TextEncoder()
+  const left = encoder.encode(a)
+  const right = encoder.encode(b)
+  let diff = left.length ^ right.length
+  const max = Math.max(left.length, right.length)
+  for (let i = 0; i < max; i += 1) diff |= (left[i] ?? 0) ^ (right[i] ?? 0)
+  return diff === 0
+}
+
+async function hmac(secret: string, message: string): Promise<string> {
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign']
+  )
+  const signature = await crypto.subtle.sign('HMAC', key, encoder.encode(message))
+  let binary = ''
+  for (const byte of new Uint8Array(signature)) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+async function verifyToken(token: string | undefined, now = Date.now()): Promise<boolean> {
+  const secret = signingSecret()
+  if (!secret || !token) return false
+
+  const parts = token.split('.')
+  if (parts.length !== 3) return false
+  const [version, expires, signature] = parts
+  if (version !== VERSION) return false
+
+  const expiry = Number(expires)
+  if (!Number.isSafeInteger(expiry) || expiry * 1000 <= now) return false
+
+  return safeEqual(signature, await hmac(secret, `${version}.${expires}`))
+}
+
+function readCookie(header: string | null | undefined, name: string): string | undefined {
+  if (!header) return undefined
+  for (const pair of header.split(';')) {
+    const eq = pair.indexOf('=')
+    if (eq === -1) continue
+    if (pair.slice(0, eq).trim() === name) return pair.slice(eq + 1).trim()
+  }
+  return undefined
+}
+
 
 /**
  * Where the board lives in this repository. Set PANEL_FILE to override; the
@@ -215,7 +306,31 @@ function configuration() {
   }
 }
 
+/**
+ * Nothing here may reach the platform as an uncaught throw.
+ *
+ * `authorized()` runs before the try that wraps the network calls, so anything
+ * it raised left the platform to answer with its own generic 500 and the
+ * SHOUTING_CODE FUNCTION_INVOCATION_FAILED — a code that names the shape of
+ * the fault and never the fault, which is how three separate fixes were aimed
+ * at a cause nobody had seen. It is the rule `middleware.ts` already lives by:
+ * it never throws, because a throw is answered by a page that names nothing.
+ *
+ * The detail is safe to return: this endpoint is behind the session, and the
+ * GitHub branch below already answers with `detail` for the same reason.
+ */
 export default async function handler(request: VercelRequest, response: VercelResponse) {
+  try {
+    return await handleRequest(request, response)
+  } catch (error) {
+    return response.status(500).json({
+      error: 'The panel API failed before it could answer.',
+      detail: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+    })
+  }
+}
+
+async function handleRequest(request: VercelRequest, response: VercelResponse) {
   response.setHeader('Cache-Control', 'no-store')
 
   if (request.method !== 'POST' && request.method !== 'GET') {
@@ -248,7 +363,8 @@ export default async function handler(request: VercelRequest, response: VercelRe
   if (problem) return response.status(400).json({ error: problem })
 
   const content = `${JSON.stringify(payload.state, null, 2)}\n`
-  if (Buffer.byteLength(content, 'utf8') > MAX_BODY_BYTES) {
+  const bytes = new TextEncoder().encode(content)
+  if (bytes.length > MAX_BODY_BYTES) {
     return response.status(413).json({ error: 'The state is too large.' })
   }
 
@@ -280,7 +396,7 @@ export default async function handler(request: VercelRequest, response: VercelRe
       headers: { ...githubHeaders, 'content-type': 'application/json' },
       body: JSON.stringify({
         message,
-        content: Buffer.from(content, 'utf8').toString('base64'),
+        content: base64(bytes),
         branch,
         ...(sha ? { sha } : {}),
       }),
@@ -308,6 +424,26 @@ export default async function handler(request: VercelRequest, response: VercelRe
   }
 }
 
+/**
+ * Base64 without `Buffer`.
+ *
+ * `Buffer` was the only runtime-specific global left on this path, and it sat
+ * on the POST side alone — so a function running anywhere but Node answered a
+ * save with a platform 500 while every GET on the same file kept working, and
+ * the panel could only report the number. `TextEncoder` and `btoa` exist in
+ * every runtime this can land in.
+ *
+ * Chunked because `String.fromCharCode(...bytes)` spreads one argument per
+ * byte: a board is far past the call-argument limit and it would throw.
+ */
+function base64(bytes: Uint8Array): string {
+  let binary = ''
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
+  }
+  return btoa(binary)
+}
+
 function safeParse(value: string): unknown {
   try {
     return JSON.parse(value)