paneltir 0.10.0 → 0.10.1

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.10.0
+   # npm install github:daifukus/paneltir#v0.10.1
    ```
 
    (Use the tag you were given; never install without pinning a version.)
@@ -237,7 +237,7 @@ identity** — never another project's.
 
    ```bash
    npx paneltir version          # version, fingerprint, where it came from
-   npx paneltir check 0.10.0      # exits non-zero if that is not what is installed
+   npx paneltir check 0.10.1      # 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.10.0
+# npm install github:daifukus/paneltir#v0.10.1
 ```
 
 Installing from Git runs the `prepare` script, which builds `dist/`, so the

package/bin/paneltir.mjs

@@ -130,10 +130,35 @@ function writeStamp(target, templateFiles, written) {
   const files = { ...(previous?.files ?? {}) }
   for (const file of written) files[file] = sha256(join(target, file))
 
+  /*
+   * The headline only advances when this run actually rewrote the whole gate.
+   *
+   * It used to advance on every run, which quietly defeated the entire point.
+   * A project on v0.9.0, a template changed in v0.10.0, `npm update`, then a
+   * re-run of `init` — which writes nothing, because the files are already
+   * there — and the stamp said the gate came from v0.10.0 while the files on
+   * disk were still v0.9.0's. `doctor` then printed "The template has not
+   * changed since" directly above a row reading BEHIND, and the panel, which
+   * has only this hash to go on, said the gate was current. Reproduced before
+   * fixing.
+   *
+   * The board is excluded because it is never rewritten: requiring it would
+   * mean the headline never advanced at all after the first install.
+   *
+   * When the gate is mixed — some files written, some left — the previous
+   * answer stands. That can over-report staleness for a partly updated gate,
+   * and it is the safe direction: `doctor`'s per-file rows carry the truth,
+   * and over-reporting sends somebody to read a diff while under-reporting
+   * sends them nowhere at all.
+   */
+  const gateFiles = templateFiles.filter((file) => file !== BOARD_SEED)
+  const wholeGate = gateFiles.length > 0 && gateFiles.every((file) => written.includes(file))
+
   const stamp = {
-    version: pkg.version,
-    templateHash: fingerprint.templateHash ?? '',
-    copiedAt: new Date().toISOString(),
+    version: wholeGate ? pkg.version : (previous?.version ?? pkg.version),
+    templateHash: wholeGate ? (fingerprint.templateHash ?? '') : (previous?.templateHash ?? ''),
+    // When this gate was last written, not when this command last ran.
+    copiedAt: written.length ? new Date().toISOString() : (previous?.copiedAt ?? new Date().toISOString()),
     files,
   }
   try {
@@ -513,9 +538,33 @@ function doctor() {
  * behalf would be the second thing in this project writing to their
  * repository.
  */
+/**
+ * One flag, in either form, because the usage line prints the space one.
+ *
+ * It only read `--cards=a,b`, while its own error message printed
+ * `[--cards a,b]` — so the documented form took `a,b` as the board path and
+ * failed with "no board at a,b", and `--by you` was dropped silently, which is
+ * worse: the run was attributed to Claude when somebody said it was theirs.
+ */
+function flag(args, name) {
+  const joined = args.find((a) => a.startsWith(`--${name}=`))
+  if (joined) return joined.slice(name.length + 3)
+  const at = args.indexOf(`--${name}`)
+  if (at !== -1 && typeof args[at + 1] === 'string' && !args[at + 1].startsWith('--')) return args[at + 1]
+  return undefined
+}
+
 async function run(args) {
-  const flags = args.filter((a) => a.startsWith('--'))
-  const plain = args.filter((a) => !a.startsWith('--'))
+  // A flag's value is not a positional argument, whichever form it came in.
+  const taken = new Set()
+  for (const name of ['cards', 'by']) {
+    const at = args.indexOf(`--${name}`)
+    if (at !== -1) {
+      taken.add(at)
+      if (typeof args[at + 1] === 'string' && !args[at + 1].startsWith('--')) taken.add(at + 1)
+    }
+  }
+  const plain = args.filter((a, i) => !a.startsWith('--') && !taken.has(i))
   const summary = plain[0]
   const file = plain[1] ?? BOARD_SEED
 
@@ -543,7 +592,7 @@ async function run(args) {
   }
 
   const board = check.board
-  const cards = (flags.find((f) => f.startsWith('--cards='))?.slice(8) ?? '')
+  const cards = (flag(args, 'cards') ?? '')
     .split(',')
     .map((id) => id.trim())
     .filter(Boolean)
@@ -557,10 +606,15 @@ async function run(args) {
     process.exit(1)
   }
 
-  const by = flags.find((f) => f.startsWith('--by='))?.slice(5) === 'you' ? 'you' : 'claude'
+  const by = flag(args, 'by') === 'you' ? 'you' : 'claude'
   const date = new Date().toISOString().slice(0, 10)
   board.runs = Array.isArray(board.runs) ? board.runs : []
-  board.runs.unshift({
+  // Appended, not prepended: `runs` is stored oldest-first and every reader
+  // reverses it. `unshift` put a new pass at the *oldest* position, so it
+  // rendered at the bottom of the revisions log and fell outside the bell's
+  // newest-first window — a record of work that read as the first thing ever
+  // done here.
+  board.runs.push({
     id: `run-${date}-${String(board.runs.length + 1).padStart(3, '0')}`,
     date,
     by,
@@ -569,8 +623,27 @@ async function run(args) {
     fingerprint: shortHash,
   })
 
+  /*
+   * Bounded here, because here is where it grows.
+   *
+   * The validators used to refuse a board with more than 200 runs while
+   * nothing anywhere trimmed them, so the only reachable outcome was a Save
+   * that broke permanently on the two-hundredth pass and said "Too many runs".
+   * A bound belongs where the list is appended, not where it is read: trimming
+   * on the write path would commit a board shorter than the one the panel is
+   * holding, and the panel would read as saved while the repository disagreed.
+   *
+   * The oldest go, since `runs` is oldest-first. Three hundred is about a
+   * decade of daily passes, and the diff of a list that only grows grows with
+   * it.
+   */
+  const KEEP_RUNS = 300
+  const dropped = Math.max(0, board.runs.length - KEEP_RUNS)
+  if (dropped) board.runs = board.runs.slice(dropped)
+
   writeFileSync(path, JSON.stringify(board, null, 2) + '\n')
   console.log(`Appended to ${file}: ${summary}`)
+  if (dropped) console.log(`  dropped the ${dropped} oldest run(s), keeping the last ${KEEP_RUNS}`)
   console.log(`  ${cards.length ? `cards ${cards.join(', ')}` : 'no cards named'} · by ${by} · ${shortHash}`)
   console.log('\nThe file is changed and not committed. The panel commits it on Save,')
   console.log('or commit it yourself — this writes nothing to your repository.')

package/dist/index.d.ts

@@ -521,6 +521,18 @@ interface SetupRequirement {
     enables?: React.ReactNode;
     /** Exactly what to do, shown only when it is missing. */
     fix?: React.ReactNode;
+    /**
+     * Information rather than a gate: drawn in the list, never walked as a step.
+     *
+     * Every other requirement here is an environment variable, and the
+     * walkthrough's one action — re-read the environment from the server —
+     * is what clears it. A requirement that action cannot clear parks the
+     * walkthrough on it for ever, and because `unknown` is judged across the
+     * whole list, one advisory row that nobody wired made every step answer a
+     * successful check with "the panel could not ask its own server". That is
+     * what the copied gate did the day it was added.
+     */
+    advisory?: boolean;
 }
 interface SetupGuideProps {
     requirements: SetupRequirement[];

package/dist/index.js

@@ -1,8 +1,8 @@
 // src/version.ts
-var PANELTIR_VERSION = "0.10.0";
-var PANELTIR_FINGERPRINT = "sha256:4de7ef7076563e4c3118ac16b645737a44c4c0675115d9a9d7bbff562d5ecb74";
+var PANELTIR_VERSION = "0.10.1";
+var PANELTIR_FINGERPRINT = "sha256:b2d1daf120972ce3bfc54f3a9f09bccaddd6ceb306a65a1682b810012d85f33d";
 var PANELTIR_FILE_COUNT = 163;
-var PANELTIR_TEMPLATE_HASH = "sha256:7f9accd11920a0c189dd683bdb96635a606960afeca71e02c2a26a0257acefd8";
+var PANELTIR_TEMPLATE_HASH = "sha256:034ba27266408af4f2ba5793d9cefbe448b168570d6a0b87dfe698dfe639feb1";
 var paneltirBuild = {
   version: PANELTIR_VERSION,
   fingerprint: PANELTIR_FINGERPRINT,
@@ -918,15 +918,16 @@ import { useState as useState5 } from "react";
 
 // src/components/Setup/wizard.ts
 function wizardStep(requirements) {
-  const total = requirements.length;
-  const done = requirements.filter((requirement) => requirement.status === "ok");
-  const unknown = requirements.some((requirement) => requirement.status === "unknown");
-  const at = requirements.findIndex((requirement) => requirement.status !== "ok");
+  const steps = requirements.filter((requirement) => !requirement.advisory);
+  const total = steps.length;
+  const done = steps.filter((requirement) => requirement.status === "ok");
+  const unknown = steps.some((requirement) => requirement.status === "unknown");
+  const at = steps.findIndex((requirement) => requirement.status !== "ok");
   if (at === -1) {
     return { current: null, index: 0, total, done, ready: total > 0, unknown: false };
   }
   return {
-    current: requirements[at],
+    current: steps[at],
     index: at + 1,
     total,
     done,
@@ -2939,7 +2940,7 @@ function applyMove(cards, move, visible) {
 function resolveTheme(saved, stored, themes, hasImported, fallback) {
   for (const name of [saved, stored]) {
     if (name === "imported" && hasImported) return "imported";
-    if (name && name in themes) return name;
+    if (name && Object.prototype.hasOwnProperty.call(themes, name)) return name;
   }
   return fallback ?? Object.keys(themes)[0];
 }
@@ -3108,6 +3109,9 @@ function PanelApp({
       // `SetupWizard` already refuses to make.
       ...gate === void 0 ? [] : [{
         id: "gate",
+        // Information, not a gate: the walkthrough's only action re-reads the
+        // environment, and this is files on disk. See SetupRequirement.
+        advisory: true,
         label: ui.needGate,
         status: gateReading.verdict === "current" ? "ok" : gateReading.verdict === "behind" ? "missing" : "unknown",
         enables: ui.needGateEnables,

package/fingerprint.json

@@ -1,8 +1,8 @@
 {
   "name": "paneltir",
-  "version": "0.10.0",
-  "hash": "sha256:4de7ef7076563e4c3118ac16b645737a44c4c0675115d9a9d7bbff562d5ecb74",
+  "version": "0.10.1",
+  "hash": "sha256:b2d1daf120972ce3bfc54f3a9f09bccaddd6ceb306a65a1682b810012d85f33d",
   "fileCount": 163,
-  "templateHash": "sha256:7f9accd11920a0c189dd683bdb96635a606960afeca71e02c2a26a0257acefd8",
-  "generatedAt": "2026-09-11T02:49:51.562Z"
+  "templateHash": "sha256:034ba27266408af4f2ba5793d9cefbe448b168570d6a0b87dfe698dfe639feb1",
+  "generatedAt": "2026-09-11T07:08:17.308Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paneltir",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "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)",
@@ -99,42 +99,56 @@
     "node": ">=20"
   },
   "paneltirRelease": {
-    "version": "0.10.0",
+    "version": "0.10.1",
     "date": "2026-09-11",
     "entries": [
       {
-        "kind": "feature",
+        "kind": "fix",
         "text": {
-          "en": "`paneltir doctor` says whether the files this project copied are still the ones the installed kit ships — and separates \"you edited it\" from \"we changed it underneath you\", which a diff cannot.",
-          "es": "`paneltir doctor` dice si los archivos que copió este proyecto siguen siendo los del kit instalado — y separa «lo editaste tú» de «lo cambiamos nosotros debajo», que un diff no puede."
+          "en": "Re-running `paneltir init` no longer tells the panel a stale gate is current. It stamped the new template over files it had not written, so a project that updated and re-ran init was told its gate was up to date when it was not.",
+          "es": "Re-ejecutar `paneltir init` ya no le dice al panel que una puerta vieja está al día. Sellaba la plantilla nueva sobre archivos que no había escrito, así que un proyecto que actualizaba y re-ejecutaba init recibía un «todo correcto» que no era cierto."
         }
       },
       {
-        "kind": "feature",
+        "kind": "fix",
+        "text": {
+          "en": "The save endpoint's own board check had drifted to a shallow one that accepted a board with no areas, an unknown intent, an unknown area and any version at all. All three copies of that check are now held to the same verdict.",
+          "es": "La comprobación del tablero en el endpoint de guardado había derivado a una superficial que aceptaba un tablero sin áreas, un intent desconocido, un área desconocida y cualquier versión. Las tres copias de esa comprobación se sujetan ahora al mismo veredicto."
+        }
+      },
+      {
+        "kind": "fix",
         "text": {
-          "en": "The setup list can carry a row for the copied gate. Import `.paneltir/gate.json` and pass it as `gate`; without it the panel says nothing about those files rather than guessing.",
-          "es": "La lista de configuración puede llevar una fila para la puerta copiada. Importa `.paneltir/gate.json` y pásalo como `gate`; sin él el panel no dice nada de esos archivos en vez de suponer."
+          "en": "`paneltir run` appends to the end of the revisions log instead of the front, so a new pass reads as the newest and not the oldest — and accepts `--cards a,b` and `--by you`, the spaced form its own usage line prints.",
+          "es": "`paneltir run` añade al final del registro de revisiones en vez de al principio, así una pasada nueva se lee como la más reciente y no como la más antigua — y acepta `--cards a,b` y `--by you`, la forma con espacio que imprime su propio uso."
         }
       },
       {
-        "kind": "feature",
+        "kind": "fix",
+        "text": {
+          "en": "A board naming a theme that only exists on Object's prototype — `constructor`, `toString` — no longer resolves as a theme and draws the panel in the browser's default colours.",
+          "es": "Un tablero que nombra un tema que sólo existe en el prototipo de Object — `constructor`, `toString` — ya no se resuelve como tema ni dibuja el panel con los colores por defecto del navegador."
+        }
+      },
+      {
+        "kind": "fix",
         "text": {
-          "en": "`paneltir run \"what this pass did\"` appends to the board's revisions, so the record does not depend on anyone remembering at the end of a session.",
-          "es": "`paneltir run \"qué hizo esta pasada\"` añade una entrada a las revisiones del tablero, así el registro no depende de que alguien se acuerde al final de la sesión."
+          "en": "Saving no longer breaks permanently once a board reaches two hundred revisions. The limit was refused on the write path and applied nowhere; it is bounded where the log is appended instead.",
+          "es": "Guardar ya no se rompe para siempre cuando un tablero llega a doscientas revisiones. El límite se rechazaba al escribir y no se aplicaba en ningún sitio; ahora se acota donde se añade al registro."
         }
       },
       {
         "kind": "fix",
         "text": {
-          "en": "`paneltir init` and `paneltir doctor` no longer need React installed. They loaded the component bundle at startup, so they failed in a project that had not installed it yet — which is exactly when `init` is run.",
-          "es": "`paneltir init` y `paneltir doctor` ya no necesitan React instalado. Cargaban el bundle de componentes al arrancar, así que fallaban en un proyecto que aún no lo tenía — que es justo cuando se ejecuta `init`."
+          "en": "The copied gate's row in the setup list no longer parks the walkthrough on a step its one action cannot clear, nor makes every other step report that the panel could not reach its own server.",
+          "es": "La fila de la puerta copiada en la lista de configuración ya no deja el asistente atascado en un paso que su única acción no puede resolver, ni hace que el resto de pasos digan que el panel no pudo alcanzar su propio servidor."
         }
       },
       {
         "kind": "chore",
         "text": {
-          "en": "The rules a project needs are checked to actually reach it: the documents a project keeps must name `extraThemes` and `paneltir doctor`, or the build fails saying why.",
-          "es": "Se comprueba que las reglas que un proyecto necesita le lleguen de verdad: los documentos que el proyecto conserva tienen que nombrar `extraThemes` y `paneltir doctor`, o la build falla diciendo por qué."
+          "en": "Two checks that could stop checking were closed: a travelling document that cannot be read is now a failure rather than a pass, and no gate file may read the environment at module scope — where no error can be caught.",
+          "es": "Se cerraron dos comprobaciones que podían dejar de comprobar: un documento que viaja y no se puede leer ahora falla en vez de pasar, y ningún archivo de la puerta puede leer el entorno a nivel de módulo, donde ningún error se puede capturar."
         }
       }
     ]

package/template/api/panel-state.ts

@@ -121,8 +121,22 @@ function readCookie(header: string | null | undefined, name: string): string | u
  * Where the board lives in this repository. Set PANEL_FILE to override; the
  * default is only a guess at a sensible place, and a wrong path here fails
  * loudly on the first save rather than quietly writing somewhere else.
+ *
+ * A function, and not a constant, for the reason `env()` above is wrapped: a
+ * bare `process.env.X` is a ReferenceError wherever `process` is undefined,
+ * and at module scope it runs *before* the handler's `try` — so it cannot be
+ * caught and the platform answers `FUNCTION_INVOCATION_FAILED`, a code that
+ * names the shape of the fault and never the fault. That is the exact failure
+ * this file has already had twice, from an import and then from a throw ahead
+ * of the wrapper. This was the last module-scope read left in any gate file.
  */
-const FILE_PATH = process.env.PANEL_FILE || 'src/data/panel-state.json'
+function filePath(): string {
+  try {
+    return process.env.PANEL_FILE || 'src/data/panel-state.json'
+  } catch {
+    return 'src/data/panel-state.json'
+  }
+}
 const MAX_BODY_BYTES = 512 * 1024
 
 interface VercelRequest {
@@ -277,6 +291,12 @@ function invalidState(state: unknown): string | null {
   }
 
   if (!Array.isArray(state.runs)) say('runs', 'must be an array')
+  // Deliberately no cap. The shape is checked here; how long a log may get is
+  // not a shape, and refusing a board for having too much history is a panel
+  // that stops saving one day and never says why. This copy used to refuse
+  // over 200 runs while nothing anywhere trimmed them, so the only outcome was
+  // a Save that broke permanently on the two-hundredth pass. Bounded on write
+  // instead, where a bound can be applied rather than only enforced.
 
   return problems.length ? problems.join('; ') : null
 }
@@ -302,7 +322,7 @@ function configuration() {
     // is how a misconfigured target gets noticed before it is written to.
     repo: repo ?? null,
     branch: process.env.PANEL_BRANCH || 'main',
-    file: FILE_PATH,
+    file: filePath(),
   }
 }
 
@@ -373,7 +393,7 @@ async function handleRequest(request: VercelRequest, response: VercelResponse) {
       ? payload.message.trim().slice(0, 120)
       : 'chore(panel): update the board from the panel'
 
-  const api = `https://api.github.com/repos/${repo}/contents/${FILE_PATH}`
+  const api = `https://api.github.com/repos/${repo}/contents/${filePath()}`
   const githubHeaders = {
     authorization: `Bearer ${token}`,
     accept: 'application/vnd.github+json',