create-grist-widget 0.3.9 → 0.3.11

package/package.json

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

package/template/AGENTS.md

@@ -30,11 +30,12 @@ rendering all live in `src/App.tsx` — that's the one file to edit.
 
 1. **Widgets use the SDK.** No direct `window.grist.*` calls — use `useGrist()` and the
    other `grist-widget-sdk` hooks.
-2. **`pnpm dev` shows the showcase hub today, not a seeded preview.** Opened outside Grist
-   it renders `TemplateLanding` (onboarding + links to released versions); the widget
-   itself only renders once actually embedded in a Grist document. An offline, seeded
-   `pnpm dev` loop is planned but not shipped in this template yet — don't describe one as
-   if it exists.
+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
+   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
+   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
    `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
@@ -49,7 +50,7 @@ rendering all live in `src/App.tsx` — that's the one file to edit.
 | Intent | Command |
 | --- | --- |
 | Install | `pnpm install` |
-| Dev server (showcase hub outside Grist) | `pnpm dev` |
+| Dev server (bare shell outside Grist, pointing at the `dev` loop) | `pnpm dev` |
 | Build | `pnpm build` |
 | Test | `pnpm test` |
 | Lint | `pnpm lint` |
@@ -87,6 +88,7 @@ Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `READM
 ## Anti-patterns
 
 - Calling `window.grist.*` inside widget code instead of the SDK's hooks
-- Describing a seeded offline `pnpm dev` preview — that doesn't exist in this template yet
-  (only a seeded offline `pnpm test`, via `renderWithGrist`, does)
+- Building or describing a seeded/live `pnpm dev` preview — deliberately not how this
+  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

package/template/README.md

@@ -4,7 +4,7 @@ Base template to build a Grist widget with `grist-widget-sdk`.
 
 `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.
 
-Opened outside a Grist iframe, `main.tsx` picks between two components purely by URL shape (`src/lib/showcase-routing.ts`, no router needed): a bare path with no recognized channel suffix renders `TemplateLanding` (its own hero, onboarding, and released-version index); `/latest/`, `/dev/`, or `/v<version>/` renders `ChannelNotice` instead — a distinct hero explaining which build this is, chips to jump to any other version/channel (`src/lib/showcase-versions.ts`), and a copy-this-URL helper for pasting into Grist's custom widget field. Both render `ScaffoldFooter` (`src/components/scaffold-footer.tsx`) at the bottom — a small, purely informational note ("Scaffolded from `create-grist-widget@X.Y.Z`") built from `package.json`'s `createGristWidgetVersion` field, which the CLI stamps on every real scaffold (`vite.config.ts` injects it as `__CREATE_GRIST_WIDGET_VERSION__`). Renders nothing if that field is absent, e.g. this pristine template source itself.
+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.
 
 When actually embedded, `GristStatusChip` (`src/components/grist-status-chip.tsx`) shows a small pill with live handshake status — connecting, retrying with a countdown, connected, or unavailable — using `useAmbientGristHandshake()` from `grist-widget-sdk/advanced`. It must be mounted *inside* `GristWidgetProvider` (see `src/main.tsx`): it only observes that provider's own handshake manager and never mounts a second one, so it's purely observational and can never duplicate or race the real handshake (see the [handshake API reference](https://gristwidgets.com/docs/sdk/api/handshake)).
 

package/template/src/components/local-dev-notice.tsx

@@ -0,0 +1,55 @@
+import {
+  Card,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+
+// Shown at the root of a local `pnpm dev` server, never inside Grist.
+// Deliberately a bare shell, not a seeded live preview: an emulator can't
+// guarantee parity with real Grist, so the loop worth trusting here is
+// `pnpm test` (renderWithGrist, headless) plus the real `dev`-branch loop
+// this points at below -- see AGENTS.md's note on why this isn't a fake
+// preview instead.
+export function LocalDevNotice() {
+  return (
+    <div className="mx-auto flex min-h-full max-w-md flex-col justify-center px-6 py-16">
+      <p className="mb-2 text-center text-sm font-medium text-muted-foreground">
+        grist-widget-template · local dev
+      </p>
+      <h1 className="text-center font-heading text-2xl font-semibold tracking-tight">
+        Not embedded in Grist
+      </h1>
+      <p className="mx-auto mt-3 mb-8 max-w-sm text-center text-sm text-muted-foreground">
+        This is a local dev server — there's no Grist here to render against.
+      </p>
+
+      <Card className="mb-4">
+        <CardHeader>
+          <CardTitle>Verify against real Grist</CardTitle>
+          <CardDescription>
+            Commit and push to <code className="text-foreground">dev</code>,
+            then open the printed{" "}
+            <code className="text-foreground">/dev/</code> URL in a real
+            Grist document — every later push self-reloads inside it within
+            seconds. See the README's Deployment section for the full loop.
+          </CardDescription>
+        </CardHeader>
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Not building this widget?</CardTitle>
+          <CardDescription>
+            <code className="text-foreground">npx grist-widget list</code> to
+            see other starting points,{" "}
+            <code className="text-foreground">
+              npx grist-widget use &lt;example&gt;
+            </code>{" "}
+            to swap this one out.
+          </CardDescription>
+        </CardHeader>
+      </Card>
+    </div>
+  )
+}

package/template/src/components/{channel-notice.tsx → release-info.tsx}

@@ -1,6 +1,5 @@
 import { useState } from "react"
 
-import { ScaffoldFooter } from "@/components/scaffold-footer"
 import { Button } from "@/components/ui/button"
 import {
   Card,
@@ -11,16 +10,15 @@ import {
 } from "@/components/ui/card"
 import { Input } from "@/components/ui/input"
 import { channelLabel, type Channel } from "@/lib/showcase-routing"
-import { devUrl, useVersions, versionUrl } from "@/lib/showcase-versions"
+import { devUrl, formatDate, useVersions, versionUrl } from "@/lib/showcase-versions"
 import { cn } from "@/lib/utils"
 
-// Shown instead of the widget tree on a specific channel build
-// (/latest/, /dev/, /v<version>/) when it's opened directly in a browser tab
-// -- not the rich showcase hub (that's `TemplateLanding`, shown when the URL
-// has no recognized channel suffix). Deliberately minimal, with its own hero
-// distinct from the hub's: this page's job is just to explain what you're
-// looking at, help you jump to a different build, and help you paste this
-// exact URL into Grist.
+// Shown on every non-embedded, built/deployed URL of this widget -- root,
+// /latest/, /dev/, /v<version>/, all carrying the same build per
+// scripts/deploy.mjs's plan() -- when opened outside Grist. Local `pnpm dev`
+// renders `LocalDevNotice` instead (see src/main.tsx): this component's
+// "paste this URL into Grist" instruction only makes sense for a real,
+// publicly reachable URL, never a bare localhost one.
 function VersionChips({ current }: { current: Channel }) {
   const { versions } = useVersions()
 
@@ -38,6 +36,7 @@ function VersionChips({ current }: { current: Channel }) {
       {versions !== null && versions.length > 0 && (
         <a
           href={versionUrl(versions[0].version)}
+          title={formatDate(versions[0].publishedAt)}
           className={chipClass(
             current.kind === "version" && current.version === versions[0].version,
           )}
@@ -52,6 +51,7 @@ function VersionChips({ current }: { current: Channel }) {
         <a
           key={v.version}
           href={versionUrl(v.version)}
+          title={formatDate(v.publishedAt)}
           className={chipClass(
             current.kind === "version" && current.version === v.version,
           )}
@@ -63,13 +63,7 @@ function VersionChips({ current }: { current: Channel }) {
   )
 }
 
-export function ChannelNotice({
-  channel,
-  hubPath,
-}: {
-  channel: Channel
-  hubPath: string
-}) {
+export function ReleaseInfo({ channel }: { channel: Channel }) {
   const [copied, setCopied] = useState(false)
   const url = window.location.href
 
@@ -90,12 +84,13 @@ export function ChannelNotice({
       </h1>
       <p className="mx-auto mt-3 mb-8 max-w-sm text-center text-sm text-muted-foreground">
         You're viewing the <span className="font-mono">{channelLabel(channel)}</span>{" "}
-        build directly, outside of Grist.
+        build directly, outside of Grist. Hover a chip below to see when it
+        shipped.
       </p>
 
       <VersionChips current={channel} />
 
-      <Card className="mb-4">
+      <Card>
         <CardHeader>
           <CardTitle>Use this as a Grist custom widget</CardTitle>
           <CardDescription>
@@ -111,15 +106,6 @@ export function ChannelNotice({
           </div>
         </CardContent>
       </Card>
-
-      <a
-        href={hubPath}
-        className="text-center text-sm text-muted-foreground underline underline-offset-4 hover:text-foreground"
-      >
-        ← Back to the template home
-      </a>
-
-      <ScaffoldFooter />
     </div>
   )
 }

package/template/src/lib/showcase-routing.ts

@@ -1,8 +1,7 @@
 // Parses the deployed URL shape every channel of this template (or a real
-// scaffolded widget) uses -- /latest/, /dev/, /v<version>/ -- so main.tsx can
-// tell a "hub" page (no recognized channel suffix, e.g. this repo's own
-// /template/) from a "channel" page (a specific release/dev build) using
-// nothing but window.location.pathname. No router needed for two states.
+// scaffolded widget) uses -- /latest/, /dev/, /v<version>/ -- so main.tsx and
+// ReleaseInfo can label the current build using nothing but
+// window.location.pathname. No router needed.
 export type Channel =
   | { kind: "latest" }
   | { kind: "dev" }
@@ -20,28 +19,41 @@ export function channelLabel(channel: Channel): string {
 }
 
 /**
- * `hubPath` is the current path with the trailing channel segment stripped,
- * e.g. "/grist-widget-sdk/template/latest/" -> "/grist-widget-sdk/template/".
- * `channel` is null when the path itself already looks like a hub (no
- * recognized suffix) -- e.g. this repo's own bare /template/, or a local
- * `pnpm dev` server at "/".
+ * `hubPath` is the current path with a recognized trailing channel segment
+ * stripped, e.g. "/grist-widget-sdk/template/latest/" ->
+ * "/grist-widget-sdk/template/" -- used to build root-relative URLs
+ * (versions.json, /dev/, /v<version>/) regardless of how deep this deploy's
+ * own base path is (see showcase-versions.ts).
+ *
+ * `channel` always resolves to something: `scripts/deploy.mjs` places the
+ * same build at the bare deployed root as at `/latest/`, so a path with no
+ * recognized suffix (the root itself, or a local `pnpm dev` server) defaults
+ * to `{ kind: "latest" }` -- that's genuinely what's there.
  */
 export function parseShowcasePath(pathname: string): {
-  channel: Channel | null
+  channel: Channel
   hubPath: string
 } {
   const trimmed = pathname.replace(/\/+$/, "")
   const segments = trimmed.split("/")
   const last = segments[segments.length - 1] ?? ""
 
-  let channel: Channel | null = null
-  if (last === "latest") channel = { kind: "latest" }
-  else if (last === "dev") channel = { kind: "dev" }
-  else {
+  let channel: Channel = { kind: "latest" }
+  let matchedSuffix = false
+  if (last === "latest") {
+    channel = { kind: "latest" }
+    matchedSuffix = true
+  } else if (last === "dev") {
+    channel = { kind: "dev" }
+    matchedSuffix = true
+  } else {
     const match = /^v(\d+\.\d+\.\d+(?:-[\w.]+)?)$/.exec(last)
-    if (match) channel = { kind: "version", version: match[1] }
+    if (match) {
+      channel = { kind: "version", version: match[1] }
+      matchedSuffix = true
+    }
   }
 
-  const hubPath = channel ? segments.slice(0, -1).join("/") + "/" : pathname
+  const hubPath = matchedSuffix ? segments.slice(0, -1).join("/") + "/" : pathname
   return { channel, hubPath }
 }

package/template/src/lib/showcase-versions.ts

@@ -2,9 +2,9 @@ import { useEffect, useState } from "react"
 
 import { parseShowcasePath } from "@/lib/showcase-routing"
 
-// Shared by the showcase hub (TemplateLanding) and the per-channel notice
-// (ChannelNotice) -- both need the same released-version list. URLs are
-// root-relative to wherever THIS deploy actually lives (derived from
+// Used by ReleaseInfo, which needs the released-version list on every
+// non-embedded, deployed URL. URLs are root-relative to wherever THIS
+// deploy actually lives (derived from
 // window.location.pathname via parseShowcasePath's hubPath), not hardcoded
 // to the grist-widget-sdk monorepo's own showcase: a real scaffolded
 // widget has its own versions.json and its own v<version>/ + dev/ dirs,

package/template/src/main.tsx

@@ -2,10 +2,10 @@ import { StrictMode } from "react"
 import { createRoot } from "react-dom/client"
 import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
 
-import { ChannelNotice } from "@/components/channel-notice"
 import { GristSdkAlerts } from "@/components/grist-sdk-alerts"
 import { GristStatusChip } from "@/components/grist-status-chip"
-import { TemplateLanding } from "@/components/template-landing"
+import { LocalDevNotice } from "@/components/local-dev-notice"
+import { ReleaseInfo } from "@/components/release-info"
 import { ThemeProvider } from "@/components/theme-provider.tsx"
 import { parseShowcasePath } from "@/lib/showcase-routing"
 import "./index.css"
@@ -13,28 +13,26 @@ import App, { GRIST_OPTIONS } from "./App.tsx"
 
 // A Grist custom widget only ever runs embedded in Grist's own iframe.
 // Opened directly in a browser tab (window.self === window.top), there's no
-// Grist to connect to. Two different "not embedded" experiences, told apart
-// purely by URL shape (see src/lib/showcase-routing.ts):
-//   - no recognized channel suffix (this repo's own bare /template/, or a
-//     local `pnpm dev` server) -> the rich showcase hub (TemplateLanding):
-//     onboarding + a link to every released version and the dev channel.
-//   - a recognized channel suffix (/latest/, /dev/, /v<version>/) -> a
-//     minimal notice: which build this is, a link back to the hub, and a
+// Grist to connect to -- two different non-embedded experiences, told apart
+// by import.meta.env.DEV (a real embed always wins over either, checked
+// first):
+//   - `pnpm dev` (DEV) -> LocalDevNotice: a bare shell pointing at the real
+//     verification loop (push to `dev`, open it in a real Grist doc) --
+//     deliberately not a live/seeded preview. An emulator can't guarantee
+//     parity with real Grist, so pretending otherwise here would teach the
+//     wrong lesson; `pnpm test` (renderWithGrist, headless) is the loop
+//     worth trusting locally. See AGENTS.md.
+//   - any built/deployed URL (root, /latest/, /dev/, /v<version>/, all
+//     carrying the same build per scripts/deploy.mjs) -> ReleaseInfo: which
+//     build this is, chips to jump to any other version/channel, and a
 //     copy-this-URL helper for pasting into Grist's custom widget field.
-// The hub always wins over embedding -- /template/ is never meant to
-// function as an actual widget, even if someone pastes it into Grist by
-// mistake.
 const isEmbedded = window.self !== window.top
-const { channel, hubPath } = parseShowcasePath(window.location.pathname)
+const { channel } = parseShowcasePath(window.location.pathname)
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
     <ThemeProvider>
-      {!channel ? (
-        <div className="min-h-full w-full bg-background text-foreground">
-          <TemplateLanding />
-        </div>
-      ) : isEmbedded ? (
+      {isEmbedded ? (
         <GristWidgetProvider options={GRIST_OPTIONS}>
           <GristStatusChip />
           <GristBoundary
@@ -47,9 +45,13 @@ createRoot(document.getElementById("root")!).render(
             </div>
           </GristBoundary>
         </GristWidgetProvider>
+      ) : import.meta.env.DEV ? (
+        <div className="min-h-full w-full bg-background text-foreground">
+          <LocalDevNotice />
+        </div>
       ) : (
         <div className="min-h-full w-full bg-background text-foreground">
-          <ChannelNotice channel={channel} hubPath={hubPath} />
+          <ReleaseInfo channel={channel} />
         </div>
       )}
     </ThemeProvider>

package/template/vite.config.ts

@@ -26,5 +26,15 @@ export default defineConfig({
   },
   test: {
     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
+    // 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,
+    // `pnpm test` exits 1 ("No test files found") on every one of those --
+    // a project that legitimately has no tests yet should report green, not
+    // red. Found live testing the real published create-grist-widget@0.3.9.
+    passWithNoTests: true,
   },
 })

package/template/src/components/scaffold-footer.tsx

@@ -1,17 +0,0 @@
-// Shown on the showcase hub and channel pages, never inside Grist (there's
-// no room, and it's not relevant to using the widget). Purely informational:
-// which create-grist-widget release this repo's package.json was scaffolded
-// from -- distinct from the repo's own `version`, which the deploy pipeline
-// always starts fresh at 0.0.1 regardless of this value (see
-// scripts/deploy.mjs's `plan()`). Renders nothing for the pristine template
-// source itself, or any copy predating this field.
-export function ScaffoldFooter() {
-  if (!__CREATE_GRIST_WIDGET_VERSION__) return null
-
-  return (
-    <p className="mt-10 text-center text-xs text-muted-foreground">
-      Scaffolded from{" "}
-      <code className="text-foreground">create-grist-widget@{__CREATE_GRIST_WIDGET_VERSION__}</code>
-    </p>
-  )
-}

package/template/src/components/template-landing.tsx

@@ -1,309 +0,0 @@
-import { useState } from "react"
-
-import { ScaffoldFooter } from "@/components/scaffold-footer"
-import { Button } from "@/components/ui/button"
-import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
-import { devUrl, formatDate, useVersions, versionUrl } from "@/lib/showcase-versions"
-
-// The showcase "hub" page: rendered whenever this deploy's URL has no
-// recognized channel suffix (see src/lib/showcase-routing.ts) -- this repo's
-// own bare /template/, or a local `pnpm dev` server. Individual channel
-// builds (/latest/, /dev/, /v<version>/) render `ChannelNotice` instead when
-// not embedded in Grist, with a link back here. Its hero introduces the
-// template project itself -- deliberately different from ChannelNotice's
-// hero, which is about the specific build you're looking at. Same component
-// for this repo's own showcase as for a real scaffolded widget that happens
-// to have something deployed at its own bare root; the only per-deploy
-// difference is which /v<version>/ dirs actually exist upstream.
-
-// A ready-to-paste instruction for an AI coding agent, not a human. Written
-// to work first-shot: it explains *why* to scaffold into a subdirectory
-// (create-grist-widget's CLI refuses a non-empty target -- and a repo
-// Claude Code is already connected to always has a .git folder) rather than
-// just saying "scaffold and push", which left room for the agent to try
-// (and fail) `npm create grist-widget .` in place.
-const CLAUDE_CODE_PROMPT = `Scaffold a new Grist custom widget here using \`npm create grist-widget\` (https://www.npmjs.com/package/create-grist-widget). This repo is an empty git clone already connected to GitHub, so scaffold into a new subdirectory first -- the CLI refuses a non-empty target directory, and this one already has a .git folder. Then push the scaffold's \`main\` and \`dev\` branches to this repository's own \`origin\` remote, so the bundled GitHub Pages deploy workflow runs. Report back the /latest/ and /v<version>/ GitHub Pages URLs once it's live.`
-
-function CopyableBlock({ text }: { text: string }) {
-  const [copied, setCopied] = useState(false)
-
-  function copy() {
-    navigator.clipboard.writeText(text).then(() => {
-      setCopied(true)
-      setTimeout(() => setCopied(false), 1500)
-    })
-  }
-
-  return (
-    <div className="relative">
-      <pre className="overflow-x-auto rounded-lg bg-muted p-4 pr-16 text-xs whitespace-pre-wrap">
-        <code>{text}</code>
-      </pre>
-      <Button
-        type="button"
-        variant="secondary"
-        size="sm"
-        className="absolute top-2 right-2"
-        onClick={copy}
-      >
-        {copied ? "Copied" : "Copy"}
-      </Button>
-    </div>
-  )
-}
-
-function CreateRepoButton() {
-  return (
-    <div className="mt-2 ml-5">
-      <Button asChild>
-        <a href="https://github.com/new" target="_blank" rel="noreferrer">
-          Create a new repository
-        </a>
-      </Button>
-    </div>
-  )
-}
-
-// The fastest path: GitHub's own "generate from template" flow, with
-// history included so gh-pages/Pages content comes along -- no
-// create-grist-widget CLI, no local install. See the template README's
-// "Used GitHub's 'Use this template' button instead of `npm create
-// grist-widget`?" note for what this trades away (package.json rename,
-// version reset) in exchange for zero local setup.
-function CopyStarterRepoButton() {
-  return (
-    <div className="mt-2 ml-5">
-      <Button asChild>
-        <a
-          href="https://github.com/arthurblanchon/grist-widget-template/generate"
-          target="_blank"
-          rel="noreferrer"
-        >
-          Copy starter repo
-        </a>
-      </Button>
-    </div>
-  )
-}
-
-export function TemplateLanding() {
-  const { versions, error } = useVersions()
-
-  return (
-    <div className="mx-auto max-w-2xl px-6 py-16">
-      <header className="mb-10 text-center">
-        <p className="mb-2 text-sm font-medium text-muted-foreground">
-          grist-widget-template
-        </p>
-        <h1 className="font-heading text-3xl font-semibold tracking-tight">
-          Build a Grist custom widget in minutes
-        </h1>
-        <p className="mx-auto mt-3 max-w-md text-sm text-muted-foreground">
-          A React + TypeScript + Tailwind starting point for{" "}
-          <code className="text-foreground">grist-widget-sdk</code>. Scaffold
-          your own copy, or browse what's already been released below.
-        </p>
-      </header>
-
-      <div className="mb-10 rounded-lg border p-4">
-        <h2 className="mb-3 font-heading text-base font-semibold">
-          Quickstart
-        </h2>
-        <ol className="list-inside list-decimal space-y-3 text-sm text-muted-foreground">
-          <li>
-            Copy this starter repo. On the next page, check{" "}
-            <strong className="text-foreground">Include all branches</strong>{" "}
-            so GitHub Pages comes already configured — no manual Settings
-            step.
-            <CopyStarterRepoButton />
-          </li>
-          <li>
-            Your new widget starts deploying on its first push. Ask your AI
-            coding agent for two URLs: the{" "}
-            <strong className="text-foreground">dev</strong> build (auto-reloads
-            as you iterate) and the{" "}
-            <strong className="text-foreground">latest</strong> build (ready to
-            paste into a production Grist document).
-          </li>
-        </ol>
-        <div className="mt-4 rounded-md border border-amber-500/40 bg-amber-500/10 p-3 text-xs text-muted-foreground">
-          <strong className="text-foreground">
-            If your AI can't see the new widget repo,
-          </strong>{" "}
-          check its GitHub App has been granted access to it:{" "}
-          <a
-            href="https://github.com/apps/claude"
-            target="_blank"
-            rel="noreferrer"
-            className="underline underline-offset-4 hover:text-foreground"
-          >
-            Claude
-          </a>
-          ,{" "}
-          <a
-            href="https://github.com/apps/chatgpt-codex-connector"
-            target="_blank"
-            rel="noreferrer"
-            className="underline underline-offset-4 hover:text-foreground"
-          >
-            Codex
-          </a>
-          , or{" "}
-          <a
-            href="https://github.com/apps/cursor"
-            target="_blank"
-            rel="noreferrer"
-            className="underline underline-offset-4 hover:text-foreground"
-          >
-            Cursor
-          </a>
-          .
-        </div>
-      </div>
-
-      <div className="mb-10 rounded-lg border p-4">
-        <h2 className="mb-3 font-heading text-base font-semibold">
-          Prefer the CLI?
-        </h2>
-        <Tabs defaultValue="claude-code">
-          <TabsList className="mb-4">
-            <TabsTrigger value="claude-code">Using Claude Code?</TabsTrigger>
-            <TabsTrigger value="manual">Manual setup</TabsTrigger>
-          </TabsList>
-
-          <TabsContent value="claude-code">
-            <ol className="list-inside list-decimal space-y-3 text-sm text-muted-foreground">
-              <li>
-                Create a new, empty GitHub repo for the widget.
-                <CreateRepoButton />
-              </li>
-              <li>
-                Install the{" "}
-                <a
-                  href="https://github.com/apps/claude"
-                  target="_blank"
-                  rel="noreferrer"
-                  className="underline underline-offset-4 hover:text-foreground"
-                >
-                  Claude GitHub App
-                </a>{" "}
-                on that repo.
-              </li>
-              <li>
-                Start a Claude Code session connected to it and paste this
-                prompt:
-                <div className="mt-2 ml-5">
-                  <CopyableBlock text={CLAUDE_CODE_PROMPT} />
-                </div>
-              </li>
-            </ol>
-          </TabsContent>
-
-          <TabsContent value="manual">
-            <ol className="list-inside list-decimal space-y-3 text-sm text-muted-foreground">
-              <li>
-                Scaffold it and try it locally:
-                <div className="mt-2 ml-5">
-                  <pre className="overflow-x-auto rounded-lg bg-muted p-4 text-xs">
-                    <code>{`npm create grist-widget my-widget
-cd my-widget
-pnpm install
-pnpm dev`}</code>
-                  </pre>
-                </div>
-              </li>
-              <li>
-                Create a new, empty GitHub repo for the widget.
-                <CreateRepoButton />
-              </li>
-              <li>
-                Push it:
-                <div className="mt-2 ml-5">
-                  <pre className="overflow-x-auto rounded-lg bg-muted p-4 text-xs">
-                    <code>{`git remote add origin https://github.com/<owner>/<repo>.git
-git push -u origin main
-git push origin dev`}</code>
-                  </pre>
-                </div>
-              </li>
-              <li>
-                Once that first push's workflow run completes (it creates a{" "}
-                <code className="text-foreground">gh-pages</code> branch),
-                enable Pages: Settings → Pages → Source → "Deploy from a
-                branch" → branch <code className="text-foreground">gh-pages</code>{" "}
-                → <code className="text-foreground">/ (root)</code>.
-                <p className="mt-2 text-xs text-muted-foreground">
-                  Not <code className="text-foreground">main</code> — that
-                  serves this repo's raw, unbuilt source instead of the built
-                  site (a blank page with a{" "}
-                  <code className="text-foreground">/src/main.tsx</code> 404
-                  in the console).
-                </p>
-                <p className="mt-2 text-xs text-muted-foreground">
-                  If that first run fails with a permissions error pushing to{" "}
-                  <code className="text-foreground">gh-pages</code>, Settings
-                  → Actions → General → Workflow permissions → "Read and
-                  write permissions" fixes it — most repos don't need this.
-                </p>
-              </li>
-            </ol>
-          </TabsContent>
-        </Tabs>
-      </div>
-
-      <section>
-        <div className="mb-3 flex items-center justify-between">
-          <h2 className="font-heading text-base font-semibold">
-            Released template versions
-          </h2>
-          <a
-            href={devUrl()}
-            className="text-sm text-muted-foreground underline underline-offset-4 hover:text-foreground"
-          >
-            Live dev preview →
-          </a>
-        </div>
-        {error ? (
-          <p className="text-sm text-muted-foreground">
-            Couldn't load the version list.
-          </p>
-        ) : versions === null ? (
-          <p className="text-sm text-muted-foreground">Loading…</p>
-        ) : versions.length === 0 ? (
-          <p className="text-sm text-muted-foreground">
-            No versions published yet.
-          </p>
-        ) : (
-          <ul className="divide-y divide-border rounded-lg border">
-            {versions.map((v, i) => (
-              <li
-                key={v.version}
-                className="flex items-center justify-between px-4 py-3"
-              >
-                <div className="flex items-center gap-2">
-                  <span className="font-mono text-sm">v{v.version}</span>
-                  {i === 0 && (
-                    <span className="rounded-full bg-primary px-2 py-0.5 text-xs text-primary-foreground">
-                      latest
-                    </span>
-                  )}
-                  <span className="text-xs text-muted-foreground">
-                    {formatDate(v.publishedAt)}
-                  </span>
-                </div>
-                <a
-                  href={versionUrl(v.version)}
-                  className="text-sm underline underline-offset-4 hover:text-foreground"
-                >
-                  Preview
-                </a>
-              </li>
-            ))}
-          </ul>
-        )}
-      </section>
-
-      <ScaffoldFooter />
-    </div>
-  )
-}