create-grist-widget 0.3.27 → 0.3.29

package/README.md

@@ -21,13 +21,14 @@ dependencies automatically, detecting whichever package manager you invoked this
 what's available — or just run `npm create grist-widget` with no name for an interactive
 prompt that asks for both.
 
-## The four commands
+## The five commands
 
 | Command | What it does |
 | --- | --- |
 | `create <name> [--example <id>]` | Scaffold a new widget into `./<name>` (the command above, or run explicitly) |
 | `init [--example <id>]` | Scaffold into the **current** directory instead of a new one — for an already-cloned or agent-initialized repo |
 | `use <example-id>` | Swap the current project's widget for a different example |
+| `upgrade` | Bring an existing widget's template files up to this version's template |
 | `list [--json]` | Print the available starting examples |
 
 Common flags for `create`/`init`: `--yes` skips interactive prompts and uses
@@ -52,7 +53,7 @@ npx create-grist-widget init --example form-edit
 ```
 
 Files that already exist and are identical to the template are left untouched; the four
-identity-bearing files (`package.json`, `README.md`, `index.html`, `src/App.tsx`) get the
+identity-bearing files (`package.json`, `README.md`, `index.html`, `src/app/App.tsx`) get the
 usual name/title substitution even if present. Anything else that already exists **and**
 differs from the template's own copy stops the run with a list of the conflicting paths —
 pass `--force` to overwrite anyway. If `.git` already exists, `init` never auto-commits;
@@ -61,18 +62,35 @@ initial commit exactly like `create` does.
 
 ### `use` — swapping to a different example later
 
-Changed your mind about which example to start from, or want to compare two? `use` swaps
-`src/App.tsx` (and any example-specific files) for a different one, in place:
+Changed your mind about which example to start from, or want to compare two? `use`
+replaces the widget, `src/app/`, with a different example:
 
 ```bash
 create-grist-widget use task-board
 ```
 
-It only ever touches `src/**` — never `main.tsx`, `vite.config.ts`, or the deploy
-workflow — and it requires a clean git working tree first (`git status --porcelain`
+It touches nothing else but the `src/components/ui/` primitives and dependencies the example
+needs — never `main.tsx`, `vite.config.ts`, or the deploy workflow — and it requires a clean git working tree first (`git status --porcelain`
 empty), so the swap is always a single reviewable, revertible diff. Commit or stash first
 if you have uncommitted changes; `use` refuses to run otherwise.
 
+### `upgrade` — picking up template changes
+
+Inside a widget, on `dev` with nothing uncommitted, after updating its `create-grist-widget`
+dependency:
+
+```bash
+pnpm exec create-grist-widget upgrade
+```
+
+It rewrites the template's files (`src/main.tsx`, the workflows, the build configuration) to
+this version's copies, deletes the ones earlier templates wrote that are gone now, merges the
+template's scripts and dependency versions into `package.json`, and drops pnpm age exceptions
+that are old enough not to matter. Nothing of the widget's own is touched (`src/app/` and its
+smoke test, `src/components/ui/`, `src/index.css`, `README.md`…). It refuses to
+run on `main`, with uncommitted changes, or on a widget still in `src/App.tsx`. Details:
+[Upgrading a widget](https://gristwidgets.com/docs/cli/upgrading).
+
 ### `list` — what's available
 
 ```bash
@@ -80,7 +98,7 @@ create-grist-widget list          # id / title / description, one per line
 create-grist-widget list --json   # the same, as JSON
 ```
 
-> **Note:** `create`, `init`, `use`, and `list` are themselves valid widget names — a bare
+> **Note:** `create`, `init`, `use`, `upgrade`, and `list` are themselves valid widget names — a bare
 > `create-grist-widget list` runs the `list` command, not "scaffold a widget named list."
 > Use the explicit form (`create-grist-widget create list`) for a widget with one of these
 > names.

package/bin/create-grist-widget.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 // create-grist-widget — scaffold a Grist custom widget, fully offline.
 //
-// Four verbs (batch H, docs/planning/2026-08-execution-plan.md §98-105):
+// Five verbs (batch H, docs/planning/2026-08-execution-plan.md §98-105, and
+// T2 of docs/planning/2026-11-01-widget-lifecycle-plan.md):
 //   create <name> [--example <id>]   scaffold a new widget into ./<name>
 //   init [--example <id>]            scaffold into the current directory
-//   use <example-id>                 swap the current project's widget
+//   use <example-id>                 swap the current project's widget (src/app/)
+//   upgrade                          bring the template's files up to this CLI's
 //   list [--json]                    print the available starting examples
 //
 // `create`/`init`/`use` share one compose engine — see
@@ -13,7 +15,8 @@
 // scripts/build-template.mjs alongside the template itself, along with
 // examples/, ui-source/, and manifest.json — see that script for why).
 // Nothing here ever hits the network: everything list/use/create --example
-// need already shipped in the tarball.
+// need already shipped in the tarball. The one exception is `upgrade`, which
+// asks the npm registry when versions in pnpm's age exceptions were published.
 
 import {
   cpSync,
@@ -33,6 +36,7 @@ import { createComposer } from "../vendor/compose-example.mjs"
 import { checkGitGate } from "../src/git-gate.mjs"
 import { addedAgeExceptions } from "../src/age-exceptions.mjs"
 import { installPlan } from "../src/package-manager.mjs"
+import { runUpgrade, upgradeRefusal } from "../src/upgrade.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 const TEMPLATE_DIR = path.join(PKG_ROOT, "template")
@@ -87,7 +91,9 @@ Usage:
   npm create grist-widget <name> [options]       Scaffold into ./<name>
   create-grist-widget create <name> [options]    Same as above, explicit
   create-grist-widget init [options]             Scaffold into the current directory
-  create-grist-widget use <example-id>           Swap the current project's widget
+  create-grist-widget use <example-id>           Replace the current project's widget (src/app/)
+  create-grist-widget upgrade                    Bring the template's files up to this CLI's
+                                                 (run it on dev, in a widget: pnpm exec create-grist-widget upgrade)
   create-grist-widget list [--json]              List available starting examples
 
 Options (create / init):
@@ -104,7 +110,7 @@ Options (create / init):
   --help, -h       Show this help
   --version, -v    Show this CLI's version
 
-Note: "create", "init", "use", and "list" are themselves valid widget names.
+Note: "create", "init", "use", "upgrade", and "list" are themselves valid widget names.
 A bare "create-grist-widget list" runs the list command, not "scaffold a
 widget named list" — use "create-grist-widget create list" for that.`)
 }
@@ -116,7 +122,7 @@ function applyIdentityEdits(target, rawName) {
     ["package.json", [["grist-widget-template-vite", rawName]]],
     ["README.md", [["grist-widget-template-vite", rawName]]],
     ["index.html", [["<title>Grist Widget</title>", `<title>${title}</title>`]]],
-    ["src/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
+    ["src/app/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
   ]
   for (const [file, subs] of edits) {
     const p = path.join(target, file)
@@ -393,7 +399,7 @@ async function cmdInit(argv) {
   // common case, a pristine "Use this template" clone); anything else that
   // already exists and differs from the template's own pristine copy blocks
   // the run, listed, unless --force.
-  const IDENTITY_FILES = new Set(["package.json", "README.md", "index.html", "src/App.tsx"])
+  const IDENTITY_FILES = new Set(["package.json", "README.md", "index.html", "src/app/App.tsx"])
   const templateFiles = listFilesRecursive(TEMPLATE_DIR)
   if (!args.force) {
     const conflicts = []
@@ -470,11 +476,21 @@ function cmdUse(argv) {
   }
 
   const cwd = process.cwd()
+  // Scaffolds older than the src/app/ layout keep their widget in src/, and
+  // their main.tsx imports ./App.tsx: an example written to src/app/ would
+  // never show.
+  if (existsSync(path.join(cwd, "src", "App.tsx"))) {
+    console.error(
+      "use: this project keeps its widget in src/App.tsx. Widgets now live in src/app/: move it there first" +
+        " (see https://gristwidgets.com/docs/cli/upgrading), then run use again."
+    )
+    process.exit(1)
+  }
   const gate = checkGitGate(cwd)
   if (!gate.ok) {
     if (gate.reason === "no-repo") {
       console.error(
-        'use: this command overwrites src/App.tsx and must run inside a git repository so the change is easy to review and undo. Run "git init" first.'
+        'use: this command replaces src/app/ and must run inside a git repository so the change is easy to review and undo. Run "git init" first.'
       )
     } else {
       console.error(
@@ -493,6 +509,105 @@ function cmdUse(argv) {
   console.log("  pnpm dev")
 }
 
+// ---------------------------------------------------------------------------
+// upgrade
+// ---------------------------------------------------------------------------
+
+const CLI_CHANGELOG_URL =
+  "https://github.com/ArthurBlanchon/grist-widget-sdk/blob/main/packages/create-grist-widget/CHANGELOG.md"
+
+/** When `name@version` was published, from the registry `npm` is configured for in `cwd`; null if unknown. */
+function npmPublishTimes(cwd) {
+  const cache = new Map()
+  return (name, version) => {
+    if (!cache.has(name)) {
+      let times = null
+      try {
+        const out = runCommand("npm", ["view", name, "time", "--json"], {
+          cwd,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 30_000,
+        })
+        times = JSON.parse(out)
+      } catch {
+        // Offline, or not on that registry: the entry stays.
+      }
+      cache.set(name, times)
+    }
+    const at = cache.get(name)?.[version]
+    return at ? new Date(at) : null
+  }
+}
+
+function printList(title, items) {
+  if (items.length === 0) return
+  console.log(`\n${title}`)
+  for (const item of items) console.log(`  ${item}`)
+}
+
+function cmdUpgrade(argv) {
+  parseArgs(argv)
+  const cwd = process.cwd()
+  const refusal = upgradeRefusal(cwd, { cliVersion: cliPkg.version })
+  if (refusal) {
+    console.error(refusal.message)
+    process.exit(1)
+  }
+
+  const report = runUpgrade({
+    cwd,
+    templateDir: TEMPLATE_DIR,
+    cliVersion: cliPkg.version,
+    publishedAt: npmPublishTimes(cwd),
+  })
+  const changed =
+    report.written.length +
+      report.deleted.length +
+      report.tsconfigs.length +
+      report.packageChanges.length +
+      report.ageRemoved.length >
+    0
+
+  const from = report.fromVersion && report.fromVersion !== cliPkg.version ? ` (from ${report.fromVersion})` : ""
+  if (!changed) {
+    console.log(`Already on create-grist-widget ${cliPkg.version}'s template: nothing to change.`)
+  } else {
+    console.log(`Upgraded to create-grist-widget ${cliPkg.version}'s template${from}.`)
+  }
+  printList("Template files rewritten:", report.written)
+  printList("Deleted (earlier templates wrote them, nothing uses them now):", report.deleted)
+  printList(
+    "Kept: earlier templates wrote these, but a file of yours still refers to them (delete them once it doesn't):",
+    report.keptRetired.map(({ file, by }) => `${file}  (by ${by.join(", ")})`)
+  )
+  printList(
+    "Switched to grist-widget-sdk's compiler settings, keeping these types:",
+    report.tsconfigs.map(({ file, types }) => `${file}  (types: ${types.join(", ") || "none"})`)
+  )
+  printList(
+    "Not switched to grist-widget-sdk's compiler settings (could not be read; do it by hand):",
+    report.tsconfigsUnreadable
+  )
+  printList("package.json:", report.packageChanges)
+  printList("pnpm age exceptions removed (old enough now that pnpm no longer needs them):", report.ageRemoved)
+  printList("pnpm age exceptions kept (their publish time could not be looked up):", report.ageUnknown)
+  if (!changed) return
+
+  console.log("\nNext:")
+  // Only what pnpm-lock.yaml records: dependencies, packageManager, age exceptions.
+  const lockfileChanges = report.packageChanges.filter((c) => /^(dependencies|devDependencies|packageManager)\b/.test(c))
+  if (lockfileChanges.length || report.ageRemoved.length) {
+    console.log("  pnpm install                                # update pnpm-lock.yaml")
+  }
+  console.log("  pnpm typecheck && pnpm lint && pnpm test")
+  console.log("  git diff                                    # review, then commit and push dev")
+  console.log(
+    `\nAnything a template change needs beyond these files is in the changelog entries${from ? ` after ${report.fromVersion}` : ""}:` +
+      `\n  ${CLI_CHANGELOG_URL}`
+  )
+}
+
 // ---------------------------------------------------------------------------
 // list
 // ---------------------------------------------------------------------------
@@ -534,6 +649,7 @@ async function main() {
   }
   if (first === "list") return cmdList(rest)
   if (first === "use") return cmdUse(rest)
+  if (first === "upgrade") return cmdUpgrade(rest)
   if (first === "init") return cmdInit(rest)
   if (first === "create") return cmdCreate(rest)
   // Bare invocation — `npm create grist-widget my-widget` (npm's `create`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.3.27",
+  "version": "0.3.29",
   "description": "Scaffold a new Grist custom widget from the grist-widget-sdk Vite template",
   "license": "MIT",
   "type": "module",

package/src/deploy.mjs

@@ -464,6 +464,9 @@ function identityEdits({ packageName, title }) {
     ["package.json", [["grist-widget-template-vite", packageName]]],
     ["README.md", [["grist-widget-template-vite", packageName]]],
     ["index.html", [["<title>Grist Widget</title>", `<title>${title}</title>`]]],
+    ["src/app/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
+    // Where the widget lived before the src/app/ layout: a repo copied from
+    // an older template repository still has it there.
     ["src/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
   ]
 }

package/src/git-gate.mjs

@@ -1,5 +1,5 @@
-// The safety gate `use <example-id>` rests on: overlayExampleSrc overwrites
-// src/App.tsx (and any other example-specific files) in place, so the only
+// The safety gate `use <example-id>` rests on: overlayExampleSrc replaces
+// src/app/ (the widget's own folder) with the example's files, so the only
 // thing that makes that recoverable is a clean git tree to diff/revert
 // against. `create`/`init` always leave a repo behind today (see
 // bin/create-grist-widget.mjs's gitInitCommit), but `use` checks for one

package/src/upgrade.mjs

@@ -0,0 +1,562 @@
+// `create-grist-widget upgrade`: bring a scaffolded widget's template files
+// up to this CLI's template (plan T2, docs/planning/2026-11-01-widget-lifecycle-plan.md).
+//
+// The template's files are an explicit list, TEMPLATE_FILES. upgrade
+// overwrites those, deletes the files earlier templates wrote that are gone
+// now (RETIRED_FILES), switches a tsconfig.app.json / tsconfig.node.json that
+// predates the SDK's base once (SDK_TSCONFIGS), merges package.json's
+// template-set scripts and dependency versions, and prunes pnpm age
+// exceptions that no longer matter. It never touches anything else: src/app/
+// (smoke test included), src/components/ui/, src/index.css, README.md and
+// every file the widget added are the widget's own. It runs on a clean `dev`,
+// so what it changed is one `git diff` to review.
+
+import { execFileSync } from "node:child_process"
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import path from "node:path"
+
+/**
+ * The files the template writes and keeps identical in every widget. Listed
+ * in the template's AGENTS.md and on the Upgrading a widget page too
+ * (tests/upgrade.test.mjs checks all three agree with the template itself).
+ */
+export const TEMPLATE_FILES = [
+  ".github/dependabot.yml",
+  ".github/workflows/ci.yml",
+  ".github/workflows/deploy.yml",
+  ".prettierignore",
+  ".prettierrc",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "components.json",
+  "eslint.config.js",
+  "src/components/theme-provider.tsx",
+  "src/lib/utils.ts",
+  "src/main.tsx",
+  "src/vite-env.d.ts",
+  "tsconfig.json",
+  "vite.config.ts",
+]
+
+/**
+ * Files earlier templates wrote that the current one doesn't: upgrade
+ * deletes each one still there, unless a file the widget keeps still refers
+ * to it (then it says which, and leaves both alone).
+ */
+export const RETIRED_FILES = [
+  "public/vite.svg",
+  "scripts/deploy.mjs",
+  "src/assets/react.svg",
+  "src/components/channel-notice.tsx",
+  "src/components/grist-sdk-alerts.tsx",
+  "src/components/grist-status-chip.tsx",
+  "src/components/local-dev-notice.tsx",
+  "src/components/release-info.tsx",
+  "src/components/scaffold-footer.tsx",
+  "src/components/template-landing.tsx",
+  "src/lib/grist-handshake-status.ts",
+  "src/lib/showcase-routing.ts",
+  "src/lib/showcase-versions.ts",
+  "vite-widget-meta.ts",
+]
+
+// ---------------------------------------------------------------------------
+// Versions
+// ---------------------------------------------------------------------------
+
+/** `[major, minor, patch]` of a plain version, or null. */
+export function parseVersion(version) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(String(version ?? "").trim())
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
+}
+
+/** Lowest version a `^x.y.z`, `~x.y.z` or `x.y.z` range allows, or null for any other range. */
+export function rangeFloor(range) {
+  const m = /^[\^~]?(\d+\.\d+\.\d+(?:[-+][\w.-]+)?)$/.exec(String(range ?? "").trim())
+  return m ? parseVersion(m[1]) : null
+}
+
+export function compareVersions(a, b) {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1
+  return 0
+}
+
+// ---------------------------------------------------------------------------
+// Refusals
+// ---------------------------------------------------------------------------
+
+function git(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+const UPGRADING_URL = "https://gristwidgets.com/docs/cli/upgrading"
+
+/**
+ * Why `upgrade` must not run in `cwd`, or null when it may.
+ *
+ * @param {string} cwd
+ * @param {{ cliVersion: string }} options
+ * @returns {null | { reason: string, message: string }}
+ */
+export function upgradeRefusal(cwd, { cliVersion }) {
+  const refuse = (reason, message) => ({ reason, message: `upgrade: ${message}` })
+
+  try {
+    git(cwd, ["rev-parse", "--is-inside-work-tree"])
+  } catch {
+    return refuse(
+      "no-repo",
+      'this command rewrites the template\'s files and must run inside a git repository, so the change is easy to review and undo. Run "git init" first.'
+    )
+  }
+
+  const pkg = readJson(path.join(cwd, "package.json"))
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies }
+  if (!pkg || !("grist-widget-sdk" in deps)) {
+    return refuse("not-a-widget", "run it at the root of a widget made with create-grist-widget (no package.json depending on grist-widget-sdk here).")
+  }
+
+  let branch = ""
+  try {
+    branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"])
+  } catch {
+    // No commit yet: not on main either.
+  }
+  if (branch === "main") {
+    return refuse("on-main", 'run it on "dev" (git switch dev): main only changes by merging dev into it, after the deploy preview there has been checked.')
+  }
+
+  if (git(cwd, ["status", "--porcelain"])) {
+    return refuse("dirty", "the working tree has uncommitted changes. Commit or stash them first, so what upgrade changes is one diff to review and undo.")
+  }
+
+  if (existsSync(path.join(cwd, "src", "App.tsx"))) {
+    return refuse(
+      "old-layout",
+      `this widget is still in src/App.tsx. Widgets now live in src/app/, which the template's src/main.tsx imports: move it there first (${UPGRADING_URL}#widgets-scaffolded-before-srcapp), then run upgrade again.`
+    )
+  }
+  if (!existsSync(path.join(cwd, "src", "app", "App.tsx"))) {
+    return refuse("no-entry", "src/app/App.tsx is missing. The template's src/main.tsx and smoke test import the widget from there.")
+  }
+
+  const madeWith = parseVersion(pkg.createGristWidgetVersion)
+  const running = parseVersion(cliVersion)
+  if (madeWith && running && compareVersions(madeWith, running) > 0) {
+    return refuse(
+      "newer-widget",
+      `this widget is already on create-grist-widget ${pkg.createGristWidgetVersion}'s template, newer than this CLI (${cliVersion}). Run the version it depends on: pnpm exec create-grist-widget upgrade.`
+    )
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// package.json
+// ---------------------------------------------------------------------------
+
+/**
+ * The widget's package.json with the template's scripts and dependency
+ * versions applied: each template script replaces the widget's of the same
+ * name; each template dependency is added if missing and raised to the
+ * template's range if the widget's allows older versions. A range that isn't
+ * plain semver on either side (workspace:, file:, a tag...) and everything
+ * else the widget has are kept.
+ *
+ * @returns {{ pkg: object, changes: string[] }}
+ */
+export function mergePackageJson(widgetPkg, templatePkg, cliVersion) {
+  const pkg = structuredClone(widgetPkg)
+  const changes = []
+
+  for (const [name, command] of Object.entries(templatePkg.scripts ?? {})) {
+    pkg.scripts ??= {}
+    if (pkg.scripts[name] === command) continue
+    changes.push(
+      name in pkg.scripts
+        ? `scripts.${name}: "${pkg.scripts[name]}" -> "${command}"`
+        : `scripts.${name}: added "${command}"`
+    )
+    pkg.scripts[name] = command
+  }
+
+  for (const section of ["dependencies", "devDependencies"]) {
+    for (const [name, range] of Object.entries(templatePkg[section] ?? {})) {
+      const owner = ["dependencies", "devDependencies"].find((s) => pkg[s] && name in pkg[s])
+      if (!owner) {
+        pkg[section] ??= {}
+        pkg[section][name] = range
+        changes.push(`${section}.${name}: added ${range}`)
+        continue
+      }
+      const current = pkg[owner][name]
+      const theirs = rangeFloor(current)
+      const ours = rangeFloor(range)
+      if (!theirs || !ours || compareVersions(ours, theirs) <= 0) continue
+      pkg[owner][name] = range
+      changes.push(`${owner}.${name}: ${current} -> ${range}`)
+    }
+  }
+
+  const manager = /^([^@]+)@(.+)$/.exec(templatePkg.packageManager ?? "")
+  const theirManager = /^([^@]+)@(.+)$/.exec(pkg.packageManager ?? "")
+  if (manager && !theirManager) {
+    pkg.packageManager = templatePkg.packageManager
+    changes.push(`packageManager: added ${templatePkg.packageManager}`)
+  } else if (manager && theirManager && manager[1] === theirManager[1]) {
+    const ours = parseVersion(manager[2].split("+")[0])
+    const theirs = parseVersion(theirManager[2].split("+")[0])
+    if (ours && theirs && compareVersions(ours, theirs) > 0) {
+      changes.push(`packageManager: ${pkg.packageManager} -> ${templatePkg.packageManager}`)
+      pkg.packageManager = templatePkg.packageManager
+    }
+  }
+
+  if (pkg.createGristWidgetVersion !== cliVersion) {
+    changes.push(`createGristWidgetVersion: ${pkg.createGristWidgetVersion ?? "(none)"} -> ${cliVersion}`)
+    pkg.createGristWidgetVersion = cliVersion
+  }
+  return { pkg, changes }
+}
+
+// ---------------------------------------------------------------------------
+// pnpm age exceptions
+// ---------------------------------------------------------------------------
+
+// pnpm 11's default minimumReleaseAge, in minutes.
+const DEFAULT_MIN_AGE_MINUTES = 24 * 60
+
+/** The `minimumReleaseAge` a pnpm-workspace.yaml sets, in minutes, or pnpm's default. */
+export function minimumReleaseAge(workspaceYaml) {
+  const m = /^minimumReleaseAge:\s*(\d+)\s*(#.*)?$/m.exec(workspaceYaml)
+  return m ? Number(m[1]) : DEFAULT_MIN_AGE_MINUTES
+}
+
+/** `{ name, versions }` for a `name@1.2.3` (or `name@1.2.3 || 1.2.4`) entry, or null for any other. */
+export function parseExactEntry(entry) {
+  const m = /^(@?[^@\s]+)@(.+)$/.exec(entry)
+  if (!m) return null
+  const versions = m[2].split("||").map((v) => v.trim())
+  return versions.every((v) => parseVersion(v)) ? { name: m[1], versions } : null
+}
+
+const KEY = "minimumReleaseAgeExclude"
+
+/**
+ * Walk the `minimumReleaseAgeExclude` list (block or flow style), passing
+ * each entry to `decide`, which returns it unchanged, a replacement, or null
+ * to drop it. The key goes too once no entry is left. Its own parser rather
+ * than age-exceptions.mjs's: pnpm writes several versions of a package as
+ * one `name@1.2.3 || 1.2.4` entry, with spaces in it.
+ */
+function rewriteAgeExceptions(workspaceYaml, decide) {
+  const flowRe = new RegExp(`^${KEY}:\\s*\\[(.*)\\]\\s*(#.*)?$`)
+  const blockRe = new RegExp(`^${KEY}:\\s*(#.*)?$`)
+  const out = []
+  let keyIndex = -1 // index in `out` of the block's key line, while in the block
+  let kept = 0
+  const closeBlock = () => {
+    if (keyIndex >= 0 && kept === 0) out.splice(keyIndex, 1)
+    keyIndex = -1
+  }
+  for (const line of workspaceYaml.split("\n")) {
+    const bare = line.replace(/\r$/, "")
+    const flow = flowRe.exec(bare)
+    if (flow) {
+      closeBlock()
+      const items = flow[1]
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .flatMap((item) => {
+          const quote = /^["']/.exec(item)?.[0] ?? ""
+          const next = decide(item.replace(/^["']|["']$/g, ""))
+          return next === null ? [] : [`${quote}${next}${quote}`]
+        })
+      if (items.length) out.push(`${KEY}: [${items.join(", ")}]${flow[2] ? ` ${flow[2]}` : ""}`)
+      continue
+    }
+    if (blockRe.test(bare)) {
+      closeBlock()
+      keyIndex = out.length
+      kept = 0
+      out.push(line)
+      continue
+    }
+    if (keyIndex >= 0) {
+      const item = /^(\s+-\s+)(["']?)(.+?)\2(\s+#.*)?\s*$/.exec(bare)
+      if (item) {
+        const next = decide(item[3])
+        if (next !== null) {
+          out.push(next === item[3] ? line : `${item[1]}${item[2]}${next}${item[2]}${item[4] ?? ""}`)
+          kept++
+        }
+        continue
+      }
+      if (!/^\s*(#.*)?$/.test(bare)) closeBlock() // the next key: the list is over
+    }
+    out.push(line)
+  }
+  closeBlock()
+  return out.join("\n")
+}
+
+/**
+ * pnpm-workspace.yaml without the `minimumReleaseAgeExclude` versions that
+ * are now older than its `minimumReleaseAge`: those exceptions no longer
+ * change what pnpm installs. Entries naming no exact version, and versions
+ * whose publish time can't be looked up, are kept.
+ *
+ * @param {string} workspaceYaml
+ * @param {{ publishedAt: (name: string, version: string) => Date | null, now: Date }} options
+ * @returns {{ yaml: string, removed: string[], unknown: string[] }}
+ */
+export function pruneAgeExceptions(workspaceYaml, { publishedAt, now }) {
+  const minAgeMs = minimumReleaseAge(workspaceYaml) * 60 * 1000
+  const removed = []
+  const unknown = []
+  const yaml = rewriteAgeExceptions(workspaceYaml, (entry) => {
+    const parsed = parseExactEntry(entry)
+    if (!parsed) return entry
+    const keep = parsed.versions.filter((version) => {
+      const at = publishedAt(parsed.name, version)
+      if (!at) {
+        unknown.push(`${parsed.name}@${version}`)
+        return true
+      }
+      if (now.getTime() - at.getTime() < minAgeMs) return true
+      removed.push(`${parsed.name}@${version}`)
+      return false
+    })
+    if (keep.length === parsed.versions.length) return entry
+    return keep.length ? `${parsed.name}@${keep.join(" || ")}` : null
+  })
+  return { yaml: removed.length ? yaml : workspaceYaml, removed, unknown }
+}
+
+// ---------------------------------------------------------------------------
+// Retired files
+// ---------------------------------------------------------------------------
+
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", "coverage"])
+const SCANNED = /\.(tsx?|jsx?|mjs|cjs|css|html|json|ya?ml)$/
+
+function listFiles(root, dir = root) {
+  const out = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(entry.name)) continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...listFiles(root, full))
+    else out.push(path.relative(root, full).split(path.sep).join("/"))
+  }
+  return out
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+/**
+ * How another file would refer to `file`: a TypeScript module by an import
+ * path ending in its name, with or without the extension (`@/lib/x`,
+ * `./x.tsx`); anything else (a script, an asset) by its full file name.
+ */
+function referencePattern(file) {
+  const base = path.posix.basename(file)
+  if (/\.tsx?$/.test(base)) {
+    const stem = base.replace(/\.tsx?$/, "")
+    return new RegExp(`/${escapeRegExp(stem)}(\\.(tsx?|jsx?))?["'\`]`)
+  }
+  return new RegExp(`(^|[/"'\`\\s(])${escapeRegExp(base)}`, "m")
+}
+
+/**
+ * Which retired files in `cwd` nothing refers to any more (`remove`), and
+ * which are still referred to, by what (`keep`). Run after the template's
+ * files are written, so their new content is what counts.
+ */
+export function retiredFilesPlan(cwd) {
+  const present = RETIRED_FILES.filter((file) => existsSync(path.join(cwd, file)))
+  const scanned = listFiles(cwd).filter(
+    (file) => SCANNED.test(file) && !present.includes(file) && file !== "pnpm-lock.yaml" && file !== "package-lock.json"
+  )
+  const contents = new Map(scanned.map((file) => [file, readFileSync(path.join(cwd, file), "utf8")]))
+  const remove = []
+  const keep = []
+  for (const file of present) {
+    const pattern = referencePattern(file)
+    const by = scanned.filter((other) => pattern.test(contents.get(other)))
+    if (by.length) keep.push({ file, by })
+    else remove.push(file)
+  }
+  return { remove, keep }
+}
+
+function removeEmptyParents(cwd, file) {
+  let dir = path.dirname(path.join(cwd, file))
+  while (dir.startsWith(cwd + path.sep) && readdirSync(dir).length === 0) {
+    rmSync(dir, { recursive: true })
+    dir = path.dirname(dir)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// tsconfig.app.json / tsconfig.node.json
+// ---------------------------------------------------------------------------
+
+/**
+ * The widget's TypeScript configs. They are the widget's (its paths and
+ * types): their compiler settings come from the grist-widget-sdk base they
+ * extend. One written before that base existed extends nothing and carries
+ * those settings itself, so upgrade switches it to the template's once.
+ */
+export const SDK_TSCONFIGS = ["tsconfig.app.json", "tsconfig.node.json"]
+
+/** JSON with comments and trailing commas, as tsconfig files allow. */
+export function parseJsonc(text) {
+  let out = ""
+  let inString = false
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (inString) {
+      out += c
+      if (c === "\\") out += text[++i] ?? ""
+      else if (c === '"') inString = false
+      continue
+    }
+    if (c === '"') {
+      inString = true
+      out += c
+    } else if (c === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i++
+      out += "\n"
+    } else if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2)
+      if (end < 0) break
+      i = end + 1
+    } else {
+      out += c
+    }
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"))
+}
+
+/**
+ * The template's version of a widget tsconfig that extends nothing yet, with
+ * the widget's `compilerOptions.types` added to the template's. Null for one
+ * that extends a base already (the SDK's, or one the widget chose).
+ *
+ * @returns {null | { content: string, types: string[] } | { unreadable: true }}
+ */
+export function migratedTsconfig(widgetText, templateText) {
+  let widget
+  try {
+    widget = parseJsonc(widgetText)
+  } catch {
+    return { unreadable: true }
+  }
+  if (widget?.extends !== undefined) return null
+  const types = widget?.compilerOptions?.types ?? []
+  const templateTypes = parseJsonc(templateText)?.compilerOptions?.types ?? []
+  const merged = [...templateTypes, ...types.filter((t) => !templateTypes.includes(t))]
+  const content = templateText.replace(/"types":\s*\[[^\]]*\]/, `"types": ${JSON.stringify(merged).replace(/","/g, '", "')}`)
+  return { content, types: merged }
+}
+
+// ---------------------------------------------------------------------------
+// The upgrade
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply `templateDir`'s template to the widget at `cwd`. Call
+ * {@link upgradeRefusal} first.
+ *
+ * @param {{
+ *   cwd: string,
+ *   templateDir: string,
+ *   cliVersion: string,
+ *   publishedAt: (name: string, version: string) => Date | null,
+ *   now?: Date,
+ * }} options
+ */
+export function runUpgrade({ cwd, templateDir, cliVersion, publishedAt, now = new Date() }) {
+  const report = {
+    fromVersion: readJson(path.join(cwd, "package.json"))?.createGristWidgetVersion ?? null,
+    written: [],
+    deleted: [],
+    keptRetired: [],
+    tsconfigs: [],
+    tsconfigsUnreadable: [],
+    packageChanges: [],
+    ageRemoved: [],
+    ageUnknown: [],
+  }
+
+  for (const file of TEMPLATE_FILES) {
+    const from = path.join(templateDir, file)
+    const to = path.join(cwd, file)
+    const next = readFileSync(from)
+    if (existsSync(to) && readFileSync(to).equals(next)) continue
+    mkdirSync(path.dirname(to), { recursive: true })
+    cpSync(from, to)
+    report.written.push(file)
+  }
+
+  for (const file of SDK_TSCONFIGS) {
+    const to = path.join(cwd, file)
+    const templateText = readFileSync(path.join(templateDir, file), "utf8")
+    if (!existsSync(to)) {
+      writeFileSync(to, templateText)
+      report.tsconfigs.push({ file, types: parseJsonc(templateText)?.compilerOptions?.types ?? [] })
+      continue
+    }
+    const migrated = migratedTsconfig(readFileSync(to, "utf8"), templateText)
+    if (!migrated) continue
+    if (migrated.unreadable) {
+      report.tsconfigsUnreadable.push(file)
+      continue
+    }
+    writeFileSync(to, migrated.content)
+    report.tsconfigs.push({ file, types: migrated.types })
+  }
+
+  const { remove, keep } = retiredFilesPlan(cwd)
+  for (const file of remove) {
+    rmSync(path.join(cwd, file))
+    removeEmptyParents(cwd, file)
+    report.deleted.push(file)
+  }
+  report.keptRetired = keep
+
+  const pkgPath = path.join(cwd, "package.json")
+  const templatePkg = JSON.parse(readFileSync(path.join(templateDir, "package.json"), "utf8"))
+  const { pkg, changes } = mergePackageJson(JSON.parse(readFileSync(pkgPath, "utf8")), templatePkg, cliVersion)
+  if (changes.length) writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n")
+  report.packageChanges = changes
+
+  const workspacePath = path.join(cwd, "pnpm-workspace.yaml")
+  if (existsSync(workspacePath)) {
+    const before = readFileSync(workspacePath, "utf8")
+    const { yaml, removed, unknown } = pruneAgeExceptions(before, { publishedAt, now })
+    if (yaml !== before) writeFileSync(workspacePath, yaml)
+    report.ageRemoved = removed
+    report.ageUnknown = unknown
+  }
+  return report
+}

package/template/AGENTS.md

@@ -11,21 +11,42 @@
 
 ## The widget contract
 
-`src/App.tsx` is the whole widget — one file, three exports:
+The widget lives in `src/app/`. Its entry point, `src/app/App.tsx`, has three exports:
 
 ```tsx
 export const GRIST_OPTIONS: UseGristOptions = { requiredAccess: "read table" }
 export const WIDGET_METADATA = { title: "...", description: "..." } as const
-export function App() {
+export default function App() {
   const w = useGrist()
   // ...
 }
 ```
 
+`GRIST_OPTIONS` may live in a file of its own, as long as `App.tsx` re-exports it: the
+template's `src/main.tsx` imports both from `./app/App`.
+
 `src/main.tsx` is one call, `mountGristWidget({ App, options: GRIST_OPTIONS, dev })` from
 `grist-widget-sdk/app`: inside Grist it renders `<App />` in `GristWidgetProvider` and
 `GristBoundary`, with the SDK's alerts and Grist's light/dark theme. Access level, column
-mapping, and rendering all live in `src/App.tsx` — that's the one file to edit.
+mapping, and rendering all live in `src/app/App.tsx` — that's the file to edit.
+
+### What is the template's, what is the widget's
+
+- **The template's:** `src/main.tsx`, `src/components/theme-provider.tsx`,
+  `src/lib/utils.ts`, `src/vite-env.d.ts`, the workflows and Dependabot config,
+  `vite.config.ts`, `tsconfig.json`, `eslint.config.js`, the Prettier config,
+  `components.json`, `CLAUDE.md` and this file.
+  Leave them as they are: `pnpm exec create-grist-widget upgrade` rewrites them to the
+  template of the `create-grist-widget` version the widget depends on
+  (<https://gristwidgets.com/docs/cli/upgrading>), and a local edit would be lost.
+- **The widget's:** everything else. `src/app/` holds its code and tests, the smoke test
+  included: put every new component, hook, helper and asset there. `src/components/ui/`
+  holds the shadcn primitives, where `shadcn add` writes (next to any other registry
+  folder it installs), and `src/index.css` the theme. `tsconfig.app.json` and
+  `tsconfig.node.json` keep the widget's own paths and types (their compiler settings come
+  from `grist-widget-sdk`). `README.md`, `index.html`, `public/` and
+  `pnpm-workspace.yaml` are the widget's too, and so is `package.json`, apart from the
+  scripts and dependency versions the template sets.
 
 ## Operating contract
 
@@ -37,7 +58,7 @@ mapping, and rendering all live in `src/App.tsx` — that's the one file to edit
    real Grist, so a fake local preview would teach the wrong lesson. Trust `pnpm test`
    (headless, real assertions) for local feedback, and the `dev`-branch loop below for real
    behavior — don't build or suggest a seeded `pnpm dev` preview.
-3. **Widget changes get a test.** `src/App.test.tsx` uses `renderWithGrist` + `presets` from
+3. **Widget changes get a test.** `src/app/App.test.tsx` uses `renderWithGrist` + `presets` from
    `grist-widget-sdk/emulator/testing` — no browser or real Grist doc needed. Run `pnpm test`.
 4. **Always develop on `dev`, release by merging to `main`.** Commit and push to `dev` for
    every change — it auto-deploys a live preview at `.../dev/` that self-reloads inside an
@@ -45,6 +66,10 @@ mapping, and rendering all live in `src/App.tsx` — that's the one file to edit
    opening the `dev` → `main` PR: merging without a version bump publishes nothing (the
    release build silently no-ops whenever that version's directory already exists — the PR
    merges cleanly and CI reports success either way).
+5. **Template updates arrive with `create-grist-widget`.** Dependabot opens a pull request of
+   its own for it. Once that is merged into `dev`, run `pnpm exec create-grist-widget upgrade`
+   on `dev` in a follow-up pull request, then `pnpm install`, `pnpm typecheck`, `pnpm lint` and
+   `pnpm test`. It rewrites only the template's files (listed above) and says what it changed.
 
 ## Commands
 
@@ -58,14 +83,16 @@ mapping, and rendering all live in `src/App.tsx` — that's the one file to edit
 | Format | `pnpm format` |
 | Type-check | `pnpm typecheck` |
 | Preview a production build | `pnpm preview` |
+| Bring the template's files up to date (on `dev`, after updating create-grist-widget) | `pnpm exec create-grist-widget upgrade` |
 
 ## Path map
 
 | Concept | Path |
 | --- | --- |
-| The widget | `src/App.tsx` |
-| Widget test (the pattern to copy for new tests) | `src/App.test.tsx` |
-| Smoke test (one smokeTestWidget call; CI runs it on SDK updates) | `src/App.smoke.test.tsx` |
+| The widget (everything in it is the widget's own) | `src/app/` |
+| Its entry point (GRIST_OPTIONS, WIDGET_METADATA, App) | `src/app/App.tsx` |
+| Widget test (the pattern to copy for new tests) | `src/app/App.test.tsx` |
+| Smoke test (one smokeTestWidget call; CI runs it on SDK updates) | `src/app/App.smoke.test.tsx` |
 | Grist wiring (mountGristWidget, inside vs. outside Grist) | `src/main.tsx` |
 | ui primitives | `src/components/ui/` |
 | Deploy workflow (runs grist-widget-deploy from the create-grist-widget devDependency: version guard, channel logic) | `.github/workflows/deploy.yml` |
@@ -85,6 +112,11 @@ creates a `gh-pages` branch — these settings can't be applied before that exis
 2. If that first workflow run fails with a permissions error pushing to `gh-pages`:
    Settings → Actions → General → Workflow permissions → **Read and write permissions**.
    Most repos don't need this; it depends on account/org defaults.
+3. After the first release (which commits to `main` and resets `dev`), a branch ruleset:
+   `main` requires a pull request and the `check` status, and blocks force pushes and
+   deletion; `dev` blocks force pushes and deletion. An agent acts through the owner's
+   account, so these rules don't tell it apart: they keep red changes off `main` whoever
+   merges. Ask the owner to set them; they need admin access.
 
 Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `README.md`.
 
@@ -95,10 +127,12 @@ Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `READM
   template works (see above); `pnpm test` is the trusted local loop, real Grist via `/dev/`
   is the trusted real one
 - Merging `dev` into `main` without bumping `package.json`'s `version` first
+- Adding widget code outside `src/app/`, or editing the template's files to change the
+  widget (see the widget contract above)
 - Adding `minimumReleaseAgeExclude` entries to `pnpm-workspace.yaml` to get an install or a
   check green, or deleting the ones pnpm wrote for `grist-widget-sdk` and `create-grist-widget` on release day (see
   `README.md`): pnpm's 24 h age check protects the widget's supply chain
 - Merging a Dependabot pull request whose `ci.yml` checks are red, or retargeting one at
-  `main`: updates go through `dev` like any other change. Template-file updates (this
-  pipeline, the build config) are applied by hand —
+  `main`: updates go through `dev` like any other change, template-file updates
+  (`pnpm exec create-grist-widget upgrade`) included —
   <https://gristwidgets.com/docs/cli/upgrading>

package/template/README.md

@@ -12,12 +12,14 @@ Opened outside a Grist iframe, the page is never a live preview of the widget it
 
 When actually embedded, the widget shows connection state only when something is wrong: until Grist is connected, or if the connection is lost or fails, `GristBoundary` replaces the widget with a connecting / unavailable / error screen (the error one with a retry button); once the widget is showing, the SDK's alerts report what needs attention (column mapping, access level, a failed write…) above it. Nothing is drawn over the widget while all is well. Pass your own `Alerts` component to `mountGristWidget()` to render them differently, or `Alerts: null` for none.
 
-`src/App.tsx` uses `useGrist<TaskRow, TaskMapped>()` for the selected row (`w.record`, `w.mode`) and remounts the UI with `key={rowKey}` when the row changes — same pattern as `widgets/create-email-draft`. It ships with two mapped columns (`title`, `done`) and an editable form that saves back via `w.table.update(...)`/`w.mapBack(...)` — the smallest real starting point, not a placeholder. See `src/grist-types.example.ts` for typing patterns.
+The widget lives in `src/app/`: `App.tsx`, and any components, hooks, helpers or assets it needs. `src/components/ui/` (shadcn primitives) and `src/index.css` (the theme) are yours too. `src/main.tsx`, the workflows and the Vite and ESLint config are the template's (`AGENTS.md` lists them): leave them as they are: `pnpm exec create-grist-widget upgrade`, run on `dev`, rewrites them when `create-grist-widget` is updated ([Upgrading a widget](https://gristwidgets.com/docs/cli/upgrading)).
+
+`src/app/App.tsx` uses `useGrist<TaskRow, TaskMapped>()` for the selected row (`w.record`, `w.mode`) and remounts the UI with `key={rowKey}` when the row changes. It ships with two mapped columns (`title`, `done`) and an editable form that saves back via `w.table.update(...)`/`w.mapBack(...)` — the smallest real starting point, not a placeholder. See `src/app/grist-types.example.ts` for typing patterns.
 
 - **ESLint** blocks direct `grist` global usage in `src/` — use the SDK only.
-- Edit `GRIST_OPTIONS.columns` in `App.tsx` to change the required columns (or remove the array entirely to read raw, unmapped records instead); `mountGristWidget()` gates the widget on `canRender` whenever columns are declared, so it renders once they're mapped.
+- Edit `GRIST_OPTIONS.columns` in `src/app/App.tsx` to change the required columns (or remove the array entirely to read raw, unmapped records instead); `mountGristWidget()` gates the widget on `canRender` whenever columns are declared, so it renders once they're mapped.
 
-Run `pnpm test`. `src/App.smoke.test.tsx` is the smoke test, one `smokeTestWidget()` call that checks the widget renders inside an emulated Grist with every declared column mapped, and that CI runs on every pull request; see `src/App.test.tsx` for the pattern (`renderWithGrist` + `presets` from `grist-widget-sdk/emulator/testing`, no browser or real Grist doc needed). Full guide: [Testing](https://gristwidgets.com/docs/emulator/testing).
+Run `pnpm test`. `src/app/App.smoke.test.tsx` is the smoke test, one `smokeTestWidget()` call that checks the widget renders inside an emulated Grist with every declared column mapped, and that CI runs on every pull request; see `src/app/App.test.tsx` for the pattern (`renderWithGrist` + `presets` from `grist-widget-sdk/emulator/testing`, no browser or real Grist doc needed). Full guide: [Testing](https://gristwidgets.com/docs/emulator/testing).
 
 **Monorepo dev:** this template resolves `grist-widget-sdk` from `packages/core/dist` (like the other widgets), not from SDK source. After changing the SDK, run `pnpm prebuild` or `pnpm --filter grist-widget-sdk build` before `pnpm dev`.
 
@@ -135,9 +137,10 @@ dependencies (`grist-widget-sdk` included) and the workflows' GitHub Actions,
 and `.github/workflows/ci.yml` lints, tests and builds every pull request.
 Merge a green one into `dev`, check `/dev/` inside Grist, then release it
 like any change (bump the version, merge `dev` into `main`). Changes to the
-template's own files (this pipeline, the build config) don't reach an
-existing widget that way: see
-[Upgrading a widget](https://gristwidgets.com/docs/cli/upgrading).
+template's own files (this pipeline, the build config) arrive with
+`create-grist-widget`'s updates: after merging one, run
+`pnpm exec create-grist-widget upgrade` on `dev` (see
+[Upgrading a widget](https://gristwidgets.com/docs/cli/upgrading)).
 
 **One-time setup** (the workflow can't do this part for you):
 
@@ -156,6 +159,20 @@ existing widget that way: see
    read-only, which would fail the push to `gh-pages` with a 403.
 3. If the repo is private, set **Pages visibility to Public** — a widget
    embeds inside a Grist iframe, which needs a publicly reachable URL.
+4. **After the first release**, protect the branches: Settings → Rules →
+   Rulesets → New branch ruleset. Not before: the first release itself
+   commits to `main` and resets `dev` (see above).
+   - `main`: **Require a pull request before merging**, **Require status
+     checks to pass** with the `check` status from `ci.yml`, **Block force
+     pushes**, **Restrict deletions**. A change then reaches `main` only
+     through a green pull request (your `dev` → `main` release PR included).
+   - `dev`: **Block force pushes** and **Restrict deletions**. Not the
+     pull-request rule: the version bump before a release is pushed straight
+     to `dev`.
+
+   An AI agent working on this repo acts through your GitHub account, so
+   these rules can't tell it from you. They guarantee the outcome (nothing
+   red reaches `main`), whoever merges.
 
 No manifest/widget-catalog file is generated — that's a multi-widget,
 Grist-widget-repository concept this single-widget template doesn't need.

package/template/package.json

@@ -35,7 +35,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.2",
-    "create-grist-widget": "^0.3.27",
+    "create-grist-widget": "^0.3.29",
     "eslint": "^10.13.0",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.7",

package/template/src/{App.smoke.test.tsx → app/App.smoke.test.tsx}

@@ -6,7 +6,10 @@
  * and it improves with each SDK release. `.github/workflows/ci.yml` runs it
  * on every pull request, Dependabot's `grist-widget-sdk` updates included:
  * an SDK release that breaks this widget turns that PR red before the merge.
- * Widget-specific assertions go in their own tests (see `App.test.tsx`).
+ *
+ * It is the widget's own file: a widget using a browser API jsdom lacks
+ * (WebGL, say) stubs it here, with `vi.mock`. Widget-specific assertions go
+ * in their own tests (see `App.test.tsx`).
  */
 import { it } from "vitest"
 import { smokeTestWidget } from "grist-widget-sdk/emulator/testing"

package/template/src/main.tsx

@@ -1,7 +1,7 @@
 import { mountGristWidget } from "grist-widget-sdk/app"
 
 import "./index.css"
-import App, { GRIST_OPTIONS } from "./App.tsx"
+import App, { GRIST_OPTIONS } from "./app/App.tsx"
 
 // Inside Grist: the widget, behind the SDK's connection screens and alerts,
 // in Grist's light/dark theme. Opened anywhere else (`pnpm dev`, a deployed

package/template/vite.config.ts

@@ -28,7 +28,7 @@ export default defineConfig({
     environment: "jsdom",
     // Most examples/<id>/ don't ship their own WidgetApp.test.tsx yet (it's
     // optional, per docs/planning/2026-08-execution-plan.md §3) --
-    // overlayExampleSrc correctly deletes the template's own App.test.tsx
+    // overlayExampleSrc correctly deletes the template's own app/App.test.tsx
     // when swapping in one that has none (it would otherwise assert against
     // content that's no longer there), so `create --example <id>` / `use
     // <id>` routinely leave a project with zero test files. Without this,

package/vendor/compose-example.mjs

@@ -29,6 +29,7 @@
 import {
   cpSync,
   existsSync,
+  mkdirSync,
   readFileSync,
   readdirSync,
   rmSync,
@@ -92,18 +93,20 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
     }
     const manifestEntry = loadManifestEntry(exampleId)
     const srcDir = join(destDir, "src")
+    const appDir = join(srcDir, "app")
 
-    // Clear whatever the previous overlay (if any) left behind, except the
-    // template's own fixed structure (components/ui, lib, index.css, etc.) —
-    // only remove files this function itself may have added, so a stale
-    // sibling from a *different* previous example doesn't linger.
-    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
-      if (entry.name === "App.tsx" || entry.name === "App.test.tsx" || entry.name === "App.smoke.test.tsx") continue
-      if (["components", "lib", "assets", "index.css", "vite-env.d.ts", "main.tsx"].includes(entry.name)) {
-        continue
-      }
-      rmSync(join(srcDir, entry.name), { recursive: true, force: true })
-    }
+    // src/app/ is the widget's own folder (see the template's AGENTS.md), so
+    // the example replaces it whole: nothing from the previous widget lingers,
+    // its test included, which would assert against content no longer there.
+    // The template's files around it (main.tsx, components/ui, lib,
+    // index.css) stay as they are.
+    rmSync(appDir, { recursive: true, force: true })
+    mkdirSync(appDir, { recursive: true })
+
+    // The template's smoke test comes back with any example: it only reads
+    // GRIST_OPTIONS, so a widget started from an example is smoke-tested too.
+    const smokeTest = join(templateDir, "src/app/App.smoke.test.tsx")
+    if (existsSync(smokeTest)) cpSync(smokeTest, join(appDir, "App.smoke.test.tsx"))
 
     // The host contract's only mismatch: examples export `WidgetApp` (no
     // default export), the template's main.tsx does a default-only import.
@@ -111,23 +114,18 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
     // stays untouched under examples/) — same idiom as deploy.mjs's
     // identityEdits.
     const widgetAppSrc = readFileSync(join(exampleDir, "WidgetApp.tsx"), "utf8")
-    writeFileSync(join(srcDir, "App.tsx"), `${widgetAppSrc}\nexport default WidgetApp\n`)
+    writeFileSync(join(appDir, "App.tsx"), `${widgetAppSrc}\nexport default WidgetApp\n`)
 
     const testPath = join(exampleDir, "WidgetApp.test.tsx")
-    const destTestPath = join(srcDir, "App.test.tsx")
     if (existsSync(testPath)) {
-      writeFileSync(destTestPath, readFileSync(testPath, "utf8"))
-    } else if (existsSync(destTestPath)) {
-      // The template's own test (or a previous example's) asserts against
-      // content that's no longer there once App.tsx is someone else's widget.
-      rmSync(destTestPath)
+      writeFileSync(join(appDir, "App.test.tsx"), readFileSync(testPath, "utf8"))
     }
 
     // Every other file living alongside WidgetApp.tsx (e.g. spreadsheet-grid's 5
     // sibling components) travels with it, verbatim.
     for (const entry of readdirSync(exampleDir, { withFileTypes: true })) {
       if (entry.name === "WidgetApp.tsx" || entry.name === "WidgetApp.test.tsx") continue
-      cpSync(join(exampleDir, entry.name), join(srcDir, entry.name), { recursive: true })
+      cpSync(join(exampleDir, entry.name), join(appDir, entry.name), { recursive: true })
     }
 
     // `@/components/ui/*` the template doesn't already vendor (per the