create-grist-widget 0.3.25 → 0.3.27

package/bin/create-grist-widget.mjs

@@ -223,7 +223,7 @@ function printAgeExceptionsNote(ageExceptions) {
     `\nNote: ${ageExceptions.join(", ")} came out less than 24 hours ago. pnpm only installs versions` +
       "\nthat recent when told to, so it listed them under minimumReleaseAgeExclude in pnpm-workspace.yaml." +
       "\nThat entry is committed: without it, every later install (yours and CI's) rejects the lockfile." +
-      "\nIt only covers the SDK released together with this CLI, and is moot once the version is a day old."
+      "\nIt only covers the SDK and CLI versions this scaffold was made with, and is moot once a day old."
   )
 }
 

package/bin/grist-widget-deploy.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// grist-widget-deploy — the GitHub Pages deploy steps a widget's
+// .github/workflows/deploy.yml runs (plan, place, remove, finalize,
+// reset-branches). See src/deploy.mjs for what each one does.
+//
+// The publish job runs this next to a `contents: write` token, after an
+// install with --ignore-scripts, so this file and src/deploy.mjs must import
+// node builtins only: no other dependency code may run there
+// (tests/deploy-imports.test.mjs).
+
+import {
+  finalize,
+  placeTarget,
+  plan,
+  removeDevDir,
+  resetBranchesIfFirstRelease,
+} from "../src/deploy.mjs"
+
+function parseArgs(argv) {
+  const out = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith("--")) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith("--")) out[key] = true
+      else {
+        out[key] = next
+        i++
+      }
+    } else out._.push(a)
+  }
+  return out
+}
+
+const [cmd, ...rest] = process.argv.slice(2)
+const args = parseArgs(rest)
+
+switch (cmd) {
+  case "plan": {
+    const result = plan(args.site, args.repo, args.event, args.ref, {
+      force: !!args.force,
+    })
+    process.stdout.write(JSON.stringify(result))
+    break
+  }
+  case "place": {
+    const res = placeTarget({
+      siteDir: args.site,
+      channel: args.channel,
+      version: args.version,
+      distDir: args.dist,
+      sha: args.sha,
+      ref: args.ref,
+      repo: args.repo,
+    })
+    console.log("placed:", JSON.stringify(res))
+    break
+  }
+  case "remove": {
+    const res = removeDevDir(args.site)
+    console.log("remove:", JSON.stringify(res))
+    break
+  }
+  case "finalize": {
+    const res = finalize({
+      siteDir: args.site,
+      updateVersions: !!args["update-versions"],
+      push: !!args.push,
+      commitMessage: args["commit-message"],
+      repo: args.repo,
+    })
+    console.log("finalize:", JSON.stringify(res))
+    break
+  }
+  case "reset-branches": {
+    const res = resetBranchesIfFirstRelease(
+      args["repo-dir"] || ".",
+      args.repo,
+      undefined,
+      args["owner-repo"] || process.env.GITHUB_REPOSITORY
+    )
+    console.log("reset-branches:", JSON.stringify(res))
+    break
+  }
+  default:
+    console.error(
+      `grist-widget-deploy: unknown subcommand "${cmd || "(none)"}". ` +
+        "Expected plan, place, remove, finalize or reset-branches."
+    )
+    process.exit(2)
+}

package/examples/reads-demo/WidgetApp.tsx

@@ -7,7 +7,8 @@ import {
 } from "grist-widget-sdk"
 
 export const GRIST_OPTIONS: UseGristOptions = {
-  requiredAccess: "read table",
+  // fetchTableRows and fetchRow read any table, which Grist only allows with full document access.
+  requiredAccess: "full",
 }
 
 export const WIDGET_METADATA = {

package/examples/safe-parse/WidgetApp.tsx

@@ -10,7 +10,8 @@ import {
 type TaskRow = { Title: string; Due: Date | null }
 
 export const GRIST_OPTIONS: UseGristOptions = {
-  requiredAccess: "read table",
+  // fetchTable reads any table, which Grist only allows with full document access.
+  requiredAccess: "full",
   suppressAlerts: ["section-not-linked"],
 }
 

package/examples/spreadsheet-grid/GristDataSheetGrid.tsx

@@ -320,7 +320,7 @@ export function GristDataSheetGrid({
       }
 
       // Sequence: deletes → updates → creates. Errors are tracked by the SDK
-      // and surfaced through `<GristSdkAlerts>`.
+      // and surfaced by the SDK's alerts (mountGristWidget).
       void (async () => {
         try {
           if (deletes.length > 0) await ops.destroy(deletes)

package/examples/spreadsheet-grid/GristSchemaToolbar.tsx

@@ -98,7 +98,7 @@ export function GristSchemaToolbar({
       setNewColId("")
       setNewType("Text")
     } catch {
-      // Surfaced via <GristSdkAlerts>.
+      // Surfaced by the SDK's alerts (mountGristWidget).
     }
   }
 
@@ -109,7 +109,7 @@ export function GristSchemaToolbar({
       await w.applyActions([gristRenameColumnAction(tableId, oldId, newId)])
       await schema.reload()
     } catch {
-      /* surfaced via <GristSdkAlerts> */
+      /* surfaced by the SDK's alerts */
     }
   }
 
@@ -118,7 +118,7 @@ export function GristSchemaToolbar({
       await w.applyActions([gristModifyColumnAction(tableId, colId, { type })])
       await schema.reload()
     } catch {
-      /* surfaced via <GristSdkAlerts> */
+      /* surfaced by the SDK's alerts */
     }
   }
 
@@ -128,7 +128,7 @@ export function GristSchemaToolbar({
       await w.applyActions([gristRemoveColumnAction(tableId, colId)])
       await schema.reload()
     } catch {
-      /* surfaced via <GristSdkAlerts> */
+      /* surfaced by the SDK's alerts */
     }
   }
 

package/manifest.json

@@ -134,7 +134,7 @@
     "id": "reads-demo",
     "title": "Reads demo",
     "description": "listTables, fetchTableRows, fetchRow, fetchSelectedRecord.",
-    "requiredAccess": "read table",
+    "requiredAccess": "full",
     "columns": [],
     "allowSelectBy": false,
     "hasCustomOptions": false,
@@ -160,7 +160,7 @@
     "id": "safe-parse",
     "title": "Safe parse",
     "description": "safeParseGristTableData with per-cell issues.",
-    "requiredAccess": "read table",
+    "requiredAccess": "full",
     "columns": [],
     "allowSelectBy": false,
     "hasCustomOptions": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.3.25",
+  "version": "0.3.27",
   "description": "Scaffold a new Grist custom widget from the grist-widget-sdk Vite template",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,8 @@
     "node": "^22.22.0 || >=24.15.0"
   },
   "bin": {
-    "create-grist-widget": "./bin/create-grist-widget.mjs"
+    "create-grist-widget": "./bin/create-grist-widget.mjs",
+    "grist-widget-deploy": "./bin/grist-widget-deploy.mjs"
   },
   "files": [
     "bin",

package/{template/scripts → src}/deploy.mjs

@@ -1,6 +1,11 @@
-#!/usr/bin/env node
 // Deploy publisher for GitHub Pages (gh-pages branch), single-widget repo.
 //
+// Shipped in create-grist-widget and run through its `grist-widget-deploy`
+// bin (bin/grist-widget-deploy.mjs) by a widget's .github/workflows/deploy.yml,
+// so a fix reaches every widget as a dependency update. The publish job runs
+// it next to a `contents: write` token: it imports node builtins only, which
+// tests/deploy-imports.test.mjs enforces.
+//
 // Adapted from the grist-widget-sdk monorepo's scripts/deploy/publish.mjs —
 // same two channels, minus the multi-widget folder loop and manifest.json
 // (there's only one widget here, so nothing to catalog):
@@ -15,7 +20,7 @@
 //     - mutable    /<repo>/dev/          (+ version.json + self-reload)
 //
 // Design notes: dependency-free (node builtins only). Pure helpers are
-// exported for testing; the CLI is a thin dispatch at the bottom.
+// exported for testing; the CLI is a thin dispatch in bin/grist-widget-deploy.mjs.
 //
 // Subcommands:
 //   plan     --site <dir> --repo <name> --event <push|workflow_dispatch>
@@ -226,11 +231,11 @@ export function injectSelfReload(html, sha) {
 /**
  * Scan siteDir for previously-released v<version>/showcase-meta.json files
  * and assemble the versions.json manifest, newest first. Read by the
- * showcase hub (TemplateLanding) and per-channel notice (ChannelNotice) to
- * show this widget's own release history -- not the grist-widget-sdk
+ * release page grist-widget-sdk/app shows outside Grist (useReleasedVersions)
+ * to list this widget's own release history -- not the grist-widget-sdk
  * monorepo's (found live: every scaffolded widget's version index showed
- * the monorepo's versions instead of its own, since showcase-versions.ts
- * used to hardcode that URL). Entries whose meta has no `repo` field, or a
+ * the monorepo's versions instead of its own, since the template's version
+ * list used to hardcode that URL). Entries whose meta has no `repo` field, or a
  * `repo` that doesn't match this repo, are skipped -- a `gh-pages` branch
  * manually seeded from another repo's export (found live) would otherwise
  * leak that repo's own version history into this one's index.
@@ -347,7 +352,9 @@ function git(args, cwd) {
 function sleep(ms) {
   // synchronous backoff (deploy step is not latency-sensitive)
   const end = Date.now() + ms
-  while (Date.now() < end) {}
+  while (Date.now() < end) {
+    // busy-wait: the retry loop runs synchronously
+  }
 }
 
 /** Regenerate versions.json (release runs only), then commit + push with rebase-retry. */
@@ -572,81 +579,3 @@ export function resetBranchesIfFirstRelease(
   git(["push", "--force", "origin", "HEAD:refs/heads/dev"], repoDir)
   return { deletedBranches, devReset: true, versionReset, identityReset, renamedFiles, installUrl }
 }
-
-// ----------------------------------------------------------------------------
-// CLI
-// ----------------------------------------------------------------------------
-
-function parseArgs(argv) {
-  const out = { _: [] }
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a.startsWith("--")) {
-      const key = a.slice(2)
-      const next = argv[i + 1]
-      if (next === undefined || next.startsWith("--")) out[key] = true
-      else { out[key] = next; i++ }
-    } else out._.push(a)
-  }
-  return out
-}
-
-function main() {
-  const [cmd, ...rest] = process.argv.slice(2)
-  const args = parseArgs(rest)
-
-  switch (cmd) {
-    case "plan": {
-      const result = plan(args.site, args.repo, args.event, args.ref, {
-        force: !!args.force,
-      })
-      process.stdout.write(JSON.stringify(result))
-      break
-    }
-    case "place": {
-      const res = placeTarget({
-        siteDir: args.site,
-        channel: args.channel,
-        version: args.version,
-        distDir: args.dist,
-        sha: args.sha,
-        ref: args.ref,
-        repo: args.repo,
-      })
-      console.log("placed:", JSON.stringify(res))
-      break
-    }
-    case "remove": {
-      const res = removeDevDir(args.site)
-      console.log("remove:", JSON.stringify(res))
-      break
-    }
-    case "finalize": {
-      const res = finalize({
-        siteDir: args.site,
-        updateVersions: !!args["update-versions"],
-        push: !!args.push,
-        commitMessage: args["commit-message"],
-        repo: args.repo,
-      })
-      console.log("finalize:", JSON.stringify(res))
-      break
-    }
-    case "reset-branches": {
-      const res = resetBranchesIfFirstRelease(
-        args["repo-dir"] || ".",
-        args.repo,
-        undefined,
-        args["owner-repo"] || process.env.GITHUB_REPOSITORY,
-      )
-      console.log("reset-branches:", JSON.stringify(res))
-      break
-    }
-    default:
-      console.error(`unknown subcommand: ${cmd || "(none)"}`)
-      process.exit(2)
-  }
-}
-
-// Only run the CLI when executed directly (not when imported by tests).
-if (import.meta.url === `file://${process.argv[1]}`) main()

package/template/.github/dependabot.yml

@@ -21,12 +21,13 @@ updates:
     cooldown:
       default-days: 7
     groups:
-      # Minor/patch bumps arrive together as one PR. grist-widget-sdk is
-      # left out so its updates get a PR of their own, whose description
-      # links its release notes.
+      # Minor/patch bumps arrive together as one PR. grist-widget-sdk and
+      # create-grist-widget (the deploy command deploy.yml runs) are left out
+      # so their updates get a PR of their own, whose description links
+      # their release notes.
       routine:
         update-types: ["minor", "patch"]
-        exclude-patterns: ["grist-widget-sdk"]
+        exclude-patterns: ["grist-widget-sdk", "create-grist-widget"]
       # @vitejs/plugin-react pins a vite major in its peer range, so their
       # majors only build when they move together.
       vite:

package/template/.github/workflows/deploy.yml

@@ -21,12 +21,16 @@ name: Deploy widget to GitHub Pages
 #   - push to dev                    -> dev channel: mutable /<repo>/dev/
 #     with version.json + a self-reload snippet, for live review inside Grist.
 #
-# All logic lives in scripts/deploy.mjs (node builtins only).
+# All logic lives in the `grist-widget-deploy` command of create-grist-widget,
+# a devDependency (node builtins only), so deploy fixes arrive as dependency
+# updates.
 #
 # Two jobs, so no dependency code ever runs next to a write token. `build`
 # installs and builds (Vite and its plugins are third-party code) with a
 # read-only token, and hands dist/ over as an artifact. `publish` holds
-# `contents: write` but installs nothing: it only runs scripts/deploy.mjs.
+# `contents: write`: it installs with --ignore-scripts, so no dependency code
+# runs, and then runs grist-widget-deploy alone, at the version the lockfile
+# pins.
 #
 # One-time setup this workflow can't do for you: enable Pages (Settings ->
 # Pages -> Source: Deploy from a branch -> gh-pages -> / (root); this workflow
@@ -53,7 +57,7 @@ on:
 # Nothing at workflow level: each job states what it needs.
 permissions: {}
 
-# Serialize deploys onto the single shared gh-pages branch. deploy.mjs
+# Serialize deploys onto the single shared gh-pages branch. grist-widget-deploy
 # additionally rebases-and-retries on push, so interleaving runs never clobber.
 concurrency:
   group: pages-gh-pages
@@ -130,7 +134,7 @@ jobs:
           REF: ${{ github.ref }}
           FORCE: ${{ github.event.inputs.force == 'true' && '--force' || '' }}
         run: |
-          PLAN=$(node scripts/deploy.mjs plan \
+          PLAN=$(node_modules/.bin/grist-widget-deploy plan \
             --site site --repo "$REPO_NAME" \
             --event "$EVENT_NAME" \
             --ref "$REF" \
@@ -179,16 +183,26 @@ jobs:
       REF: ${{ github.ref }}
     steps:
       # Credentials stay persisted here: the first-release reset below pushes
-      # with them. Nothing in this job installs or runs dependency code.
+      # with them. No dependency code runs in this job (see the install step).
       - name: Checkout
         uses: actions/checkout@v7
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
       - name: Setup Node
         uses: actions/setup-node@v7
         with:
           node-version: 22
           package-manager-cache: false
 
+      # Only for grist-widget-deploy, at the version (and integrity hash) the
+      # lockfile pins. --ignore-scripts: no dependency's install script runs,
+      # and the steps below call the bin directly, never through `pnpm
+      # exec`/`pnpm run`, whose dependency check may reinstall with scripts.
+      - name: Install the deploy command
+        run: pnpm install --ignore-scripts
+
       - name: Clone gh-pages into ./site
         env:
           GH_TOKEN: ${{ github.token }}
@@ -219,7 +233,7 @@ jobs:
           SHA="$(git rev-parse --short HEAD)"
           VERSION_ARG=""
           [ -n "$VERSION" ] && VERSION_ARG="--version $VERSION"
-          node scripts/deploy.mjs place \
+          node_modules/.bin/grist-widget-deploy place \
             --site site --repo "$REPO_NAME" \
             --channel "$CONTEXT" $VERSION_ARG \
             --dist dist \
@@ -237,13 +251,13 @@ jobs:
           if [ "$CONTEXT" = "release" ]; then
             UPDATE_VERSIONS="--update-versions"
           fi
-          node scripts/deploy.mjs finalize \
+          node_modules/.bin/grist-widget-deploy finalize \
             --site site --repo "$REPO_NAME" $UPDATE_VERSIONS --push \
             --commit-message "deploy: ${CONTEXT} @ ${SHA_FULL}"
 
       - name: Reset repo to a clean first-release state
         if: needs.build.outputs.context == 'release' && needs.build.outputs.firstRelease == 'true'
-        run: node scripts/deploy.mjs reset-branches --repo "$REPO_NAME"
+        run: node_modules/.bin/grist-widget-deploy reset-branches --repo "$REPO_NAME"
 
   cleanup:
     # When the `dev` branch is deleted, remove /dev/ so the dev URL retires
@@ -253,15 +267,22 @@ jobs:
     permissions:
       contents: write
     steps:
-      - name: Checkout (default branch — for scripts/deploy.mjs)
+      - name: Checkout (default branch — for its pinned grist-widget-deploy)
         uses: actions/checkout@v7
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
       - name: Setup Node
         uses: actions/setup-node@v7
         with:
           node-version: 22
           package-manager-cache: false
 
+      # As in `publish`: no dependency scripts run, and the bin is called directly.
+      - name: Install the deploy command
+        run: pnpm install --ignore-scripts
+
       - name: Clone gh-pages into ./site (skip if it does not exist)
         id: clone
         env:
@@ -283,7 +304,7 @@ jobs:
         env:
           DELETED_REF: ${{ github.event.ref }}
         run: |
-          node scripts/deploy.mjs remove --site site
-          node scripts/deploy.mjs finalize \
+          node_modules/.bin/grist-widget-deploy remove --site site
+          node_modules/.bin/grist-widget-deploy finalize \
             --site site --push \
             --commit-message "cleanup: retire dev URL for ${DELETED_REF}"

package/template/AGENTS.md

@@ -22,16 +22,17 @@ export function App() {
 }
 ```
 
-`src/main.tsx` wires it into Grist: `GristWidgetProvider` (reads `GRIST_OPTIONS`) →
-`GristBoundary` → `GristSdkAlerts` → `<App />`. Access level, column mapping, and
-rendering all live in `src/App.tsx` — that's the one file to edit.
+`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.
 
 ## Operating contract
 
 1. **Widgets use the SDK.** No direct `window.grist.*` calls — use `useGrist()` and the
    other `grist-widget-sdk` hooks.
 2. **`pnpm dev` is a bare shell, on purpose — not a seeded preview.** Opened outside Grist
-   it renders `LocalDevNotice`; the widget itself only renders once actually embedded in a
+   it shows the SDK's local-dev page; the widget itself only renders once actually embedded in a
    Grist document. This is deliberate, not a gap: an emulator can't guarantee parity with
    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
@@ -64,10 +65,10 @@ rendering all live in `src/App.tsx` — that's the one file to edit.
 | --- | --- |
 | The widget | `src/App.tsx` |
 | Widget test (the pattern to copy for new tests) | `src/App.test.tsx` |
-| Grist wiring / embed vs. showcase detection | `src/main.tsx` |
+| Smoke test (one smokeTestWidget call; CI runs it on SDK updates) | `src/App.smoke.test.tsx` |
+| Grist wiring (mountGristWidget, inside vs. outside Grist) | `src/main.tsx` |
 | ui primitives | `src/components/ui/` |
-| Deploy workflow | `.github/workflows/deploy.yml` |
-| Deploy script (version guard, channel logic) | `scripts/deploy.mjs` |
+| Deploy workflow (runs grist-widget-deploy from the create-grist-widget devDependency: version guard, channel logic) | `.github/workflows/deploy.yml` |
 | Pull request checks (lint, test, build) | `.github/workflows/ci.yml` |
 | Dependency update PRs (weekly, against the dev branch) | `.github/dependabot.yml` |
 | Full walkthrough (dev loop, deploying, embedding) | `README.md` |
@@ -95,7 +96,7 @@ Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `READM
   is the trusted real one
 - Merging `dev` into `main` without bumping `package.json`'s `version` first
 - Adding `minimumReleaseAgeExclude` entries to `pnpm-workspace.yaml` to get an install or a
-  check green, or deleting the one pnpm wrote for `grist-widget-sdk` on release day (see
+  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

package/template/README.md

@@ -6,18 +6,18 @@ Base template to build a Grist widget with `grist-widget-sdk`.
 **Install URL**: written here by this widget's first release (its GitHub Pages `/latest/` URL).
 <!-- install-url:end -->
 
-`src/main.tsx` wraps the app with `GristWidgetProvider`, `GristBoundary`, and `GristSdkAlerts`. The latter maps `getGristSdkAlertDescriptors()` from the SDK to shadcn `Alert` (`src/components/grist-sdk-alerts.tsx` + `src/components/ui/alert.tsx`); keep them in sync with the playground when you change alert styling.
+`src/main.tsx` is one call to `mountGristWidget()` from `grist-widget-sdk/app` ([reference](https://gristwidgets.com/docs/sdk/api/app)). Inside Grist it renders `App` in `GristWidgetProvider` and `GristBoundary`, under the SDK's alerts, in Grist's light/dark theme. `src/components/theme-provider.tsx` re-exports its `useTheme()`, for shadcn components that need the theme in JavaScript.
 
-Opened outside a Grist iframe, `main.tsx` picks between two components — never a live preview of the widget itself, since nothing here proves anything about real Grist behavior: local `pnpm dev` renders `LocalDevNotice`, a bare shell pointing at the real verification loop below (push to `dev`, open it in a real Grist document); any built/deployed URL (root, `/latest/`, `/dev/`, `/v<version>/` — all carrying the same build, see Deployment below) renders `ReleaseInfo` instead — which build this is, chips to jump to any other version/channel (hover one to see when it shipped; `src/lib/showcase-versions.ts`), and a copy-this-URL helper for pasting into Grist's custom widget field.
+Opened outside a Grist iframe, the page is never a live preview of the widget itself, since nothing there proves anything about real Grist behavior. Local `pnpm dev` shows a local-dev page pointing at the real verification loop below (push to `dev`, open it in a real Grist document). Any built or deployed URL (root, `/latest/`, `/dev/`, `/v<version>/`, all carrying the same build, see Deployment below) shows a release page instead: which build this is, links to every other version and channel (hover one to see when it shipped), and the URL to paste into Grist's custom widget field. Both come from the SDK and follow this widget's shadcn colors; `mountGristWidget()` takes your own components instead (`LocalDevPage`, `ReleasePage`).
 
-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, `GristSdkAlerts` reports what needs attention (column mapping, access level, a failed write…). Nothing is drawn over the widget while all is well.
+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.
 
 - **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); `main.tsx` sets `GristBoundary gate="canRender"` whenever columns are declared. Mapping alerts use `GristSdkAlerts`.
+- 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.
 
-Run `pnpm test` — 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.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).
 
 **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`.
 
@@ -43,11 +43,12 @@ pnpm, even under `npm create`, unless it was run with `--no-install` or
 without pnpm installed. Versions are pinned with their integrity hashes, CI
 installs exactly that, and Dependabot updates it. A `package-lock.json` isn't
 used: the workflows install with pnpm. pnpm 11 won't install a version
-published less than 24 hours ago. So a widget scaffolded on the day of an SDK
-release also gets one `minimumReleaseAgeExclude` entry in
-`pnpm-workspace.yaml`, for that SDK version only, written by pnpm itself.
-Keep it: without it, every install (yours and CI's) rejects the lockfile
-until the version is a day old. After that the entry is harmless.
+published less than 24 hours ago. So a widget scaffolded on the day of a
+release also gets `minimumReleaseAgeExclude` entries in `pnpm-workspace.yaml`,
+written by pnpm itself, for the `grist-widget-sdk` and `create-grist-widget`
+versions it was made with, and nothing else. Keep them: without them, every
+install (yours and CI's) rejects the lockfile until the version is a day old.
+After that the entries are harmless.
 
 ### Live preview
 
@@ -68,8 +69,10 @@ directory, same as `scripts/smoke/create-widget.sh` does.
 
 ## Deployment
 
-A bundled GitHub Actions workflow (`.github/workflows/deploy.yml` +
-`scripts/deploy.mjs`) publishes this widget to **your own** GitHub Pages.
+A bundled GitHub Actions workflow (`.github/workflows/deploy.yml`, which runs
+the `grist-widget-deploy` command of the `create-grist-widget` devDependency)
+publishes this widget to **your own** GitHub Pages. Fixes to the deploy logic
+arrive as updates of that devDependency.
 
 ### The workflow: always develop on `dev`, release by merging to `main`
 

package/template/package.json

@@ -17,7 +17,7 @@
     "@tailwindcss/vite": "^4.3.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "grist-widget-sdk": "^0.3.25",
+    "grist-widget-sdk": "^0.3.27",
     "lucide-react": "^1.61.0",
     "radix-ui": "^1.8.1",
     "react": "^19.3.1",
@@ -35,6 +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",
     "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

@@ -0,0 +1,17 @@
+/**
+ * Smoke test: the widget renders inside an emulated Grist, mounted as
+ * `main.tsx` mounts it, with every column `GRIST_OPTIONS` declares mapped.
+ *
+ * It only reads `GRIST_OPTIONS`, so it stays valid as the widget changes,
+ * 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`).
+ */
+import { it } from "vitest"
+import { smokeTestWidget } from "grist-widget-sdk/emulator/testing"
+
+import App, { GRIST_OPTIONS } from "./App"
+
+it("renders inside Grist with every declared column mapped", () =>
+  smokeTestWidget({ App, options: GRIST_OPTIONS }))