create-grist-widget 0.2.14 → 0.2.17

package/package.json

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

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

@@ -132,7 +132,7 @@ jobs:
             UPDATE_VERSIONS="--update-versions"
           fi
           node scripts/deploy.mjs finalize \
-            --site site $UPDATE_VERSIONS --push \
+            --site site --repo "$REPO_NAME" $UPDATE_VERSIONS --push \
             --commit-message "deploy: ${{ steps.plan.outputs.context }} @ ${{ github.sha }}"
 
   cleanup:

package/template/README.md

@@ -6,7 +6,7 @@ Base template to build a Grist widget with `grist-widget-sdk`.
 
 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.
 
-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 `useGristHandshakeContext()` from `grist-widget-sdk/advanced` in its own `<GristHandshakeProvider>`. Safe to mount alongside `GristWidgetProvider`: both share the page's `ensureGristReady()` singleton (see `apps/docs/api/handshake.md`), so this is purely observational and never duplicates the real handshake.
+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 `apps/docs/api/handshake.md`).
 
 `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`. See `src/grist-types.example.ts` for typing patterns.
 
@@ -86,6 +86,22 @@ of changes — it's the permanent working/preview branch for this widget, not
 a one-off feature branch to delete and recreate. Deleting it retires `/dev/`
 automatically.
 
+> ⚠️ **Used GitHub's "Use this template" button instead of `npm create
+> grist-widget`?** That path copies this repo's default branch verbatim —
+> it doesn't run any of the CLI's own setup (renaming `package.json`,
+> titles, etc.), and it won't reset `package.json`'s `version` back to a
+> fresh `0.0.1` for you. Do both by hand before your first real release.
+> If you also checked **"Include all branches"** (to get `gh-pages`/Pages
+> already set up, no manual Settings step), your first real release
+> automatically clears out every leftover `v<version>/` it finds — a
+> `v<version>/` only counts as a genuine prior release once it carries a
+> `showcase-meta.json` naming *this* repo (written by this pipeline's own
+> `place` step), so on a repo with no genuine releases yet, everything
+> else is provably inherited noise and gets safely wiped on your first
+> push to `main`. That cleanup only ever runs before your *first* genuine
+> release — once one exists, it's permanently a no-op, so it's still safest
+> to never manually re-seed `gh-pages` again after that point.
+
 **One-time setup** (the workflow can't do this part for you):
 
 1. **Settings → Pages** → Source: "Deploy from a branch" → branch `gh-pages`

package/template/package.json

@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5.2.8",
-    "grist-widget-sdk": "^0.2.1",
+    "grist-widget-sdk": "^0.2.15",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/template/scripts/deploy.mjs

@@ -58,10 +58,33 @@ export function basePathFor(repo, channel, version) {
   return `/${repo}/${leaf}/`
 }
 
+/**
+ * Was `versionDir` actually published by *this* repo's own pipeline? Checks
+ * for a `showcase-meta.json` whose `repo` field matches -- not just that the
+ * directory exists. A `gh-pages` branch manually seeded from another repo's
+ * export (found live: a freshly-created widget repo's `gh-pages` already
+ * contained `v<version>/` directories copied from the template repo it came
+ * from, some with no meta file at all, one with a foreign `showcase-meta.json`
+ * whose `sha` didn't belong to this repo's own history) would otherwise look
+ * indistinguishable from a real prior release and get silently treated as
+ * "already published" forever, permanently squatting on that version path.
+ */
+function isGenuineRelease(versionDir, repo) {
+  const metaPath = join(versionDir, "showcase-meta.json")
+  if (!existsSync(metaPath)) return false
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, "utf8"))
+    return meta.repo === repo
+  } catch {
+    return false
+  }
+}
+
 /**
  * Build the release/dev plan from this repo's own package.json + the current
- * gh-pages tree. Release is skipped when its immutable v<version> dir already
- * exists (unless force), so re-pushing main without a version bump is a no-op.
+ * gh-pages tree. Release is skipped when its immutable v<version> dir was
+ * genuinely published by this repo before (unless force), so re-pushing main
+ * without a version bump is a no-op.
  */
 export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   const isRelease = event === "workflow_dispatch" || ref === "refs/heads/main" || ref === "main"
@@ -72,7 +95,7 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   const version = pkg.version
   if (!version) throw new Error("package.json has no version")
   const versionDir = join(siteDir, `v${version}`)
-  const exists = existsSync(versionDir)
+  const exists = isGenuineRelease(versionDir, repo)
   return {
     context: "release",
     version,
@@ -125,15 +148,19 @@ export function injectSelfReload(html, sha) {
  * show 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).
+ * 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.
  */
-export function buildVersionsManifest(siteDir) {
+export function buildVersionsManifest(siteDir, repo) {
   const entries = []
   for (const name of existsSync(siteDir) ? readdirSync(siteDir) : []) {
     if (!/^v\d+\.\d+\.\d+/.test(name)) continue
     const metaPath = join(siteDir, name, "showcase-meta.json")
     if (!existsSync(metaPath)) continue
     const meta = JSON.parse(readFileSync(metaPath, "utf8"))
+    if (meta.repo !== repo) continue
     entries.push({ version: meta.version, publishedAt: meta.publishedAt })
   }
   entries.sort((a, b) => new Date(b.publishedAt) - new Date(a.publishedAt))
@@ -150,8 +177,31 @@ function replaceDir(dest, srcDist) {
   cpSync(srcDist, dest, { recursive: true })
 }
 
+/**
+ * If this repo has never genuinely published a release before (no
+ * v<version>/ directory whose showcase-meta.json matches this repo), any
+ * v<version>/ directories present are provably inherited noise -- e.g. from
+ * copying this template repo including its gh-pages branch (GitHub's "Use
+ * this template" -> "Include all branches"). Safe to clear them all before
+ * placing this repo's actual first release: there is no ambiguity, since a
+ * repo with zero genuine releases can't have any of its own history to lose.
+ * Never touches dev/, latest/, or site-root files. Once a genuine release
+ * exists for this repo, buildVersionsManifest is non-empty and this is
+ * permanently a no-op.
+ */
+export function cleanupForeignVersionsIfFirstRelease(siteDir, repo) {
+  if (buildVersionsManifest(siteDir, repo).length > 0) return { cleaned: [] }
+  const cleaned = []
+  for (const name of existsSync(siteDir) ? readdirSync(siteDir) : []) {
+    if (!/^v\d+\.\d+\.\d+/.test(name)) continue
+    rmSync(join(siteDir, name), { recursive: true, force: true })
+    cleaned.push(name)
+  }
+  return { cleaned }
+}
+
 /** Place a freshly built dist into the gh-pages tree. */
-export function placeTarget({ siteDir, channel, version, distDir, sha, ref }) {
+export function placeTarget({ siteDir, channel, version, distDir, sha, ref, repo }) {
   if (!existsSync(distDir)) throw new Error(`dist not found: ${distDir}`)
   if (channel === "dev") {
     const devDir = join(siteDir, "dev")
@@ -175,11 +225,12 @@ export function placeTarget({ siteDir, channel, version, distDir, sha, ref }) {
   // exactly like latest/ reusing it: the asset URLs it references (under
   // v<version>/assets/) already exist from the versionDir placement above,
   // so nothing 404s.
+  cleanupForeignVersionsIfFirstRelease(siteDir, repo)
   const versionDir = join(siteDir, `v${version}`)
   replaceDir(versionDir, distDir)
   writeFileSync(
     join(versionDir, "showcase-meta.json"),
-    JSON.stringify({ version, publishedAt: new Date().toISOString(), sha }, null, 2) + "\n",
+    JSON.stringify({ version, publishedAt: new Date().toISOString(), sha, repo }, null, 2) + "\n",
   )
   const latestDir = join(siteDir, "latest")
   replaceDir(latestDir, distDir)
@@ -211,9 +262,9 @@ function sleep(ms) {
 }
 
 /** Regenerate versions.json (release runs only), then commit + push with rebase-retry. */
-export function finalize({ siteDir, updateVersions, push, commitMessage, remoteBranch = "gh-pages" }) {
+export function finalize({ siteDir, updateVersions, push, commitMessage, remoteBranch = "gh-pages", repo }) {
   if (updateVersions) {
-    const versions = buildVersionsManifest(siteDir)
+    const versions = buildVersionsManifest(siteDir, repo)
     writeFileSync(join(siteDir, "versions.json"), JSON.stringify(versions, null, 2) + "\n")
   }
   git(["add", "-A"], siteDir)
@@ -282,6 +333,7 @@ function main() {
         distDir: args.dist,
         sha: args.sha,
         ref: args.ref,
+        repo: args.repo,
       })
       console.log("placed:", JSON.stringify(res))
       break
@@ -297,6 +349,7 @@ function main() {
         updateVersions: !!args["update-versions"],
         push: !!args.push,
         commitMessage: args["commit-message"],
+        repo: args.repo,
       })
       console.log("finalize:", JSON.stringify(res))
       break

package/template/src/components/grist-status-chip.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from "react"
-import { GristHandshakeProvider, useGristHandshakeContext } from "grist-widget-sdk/advanced"
+import { useAmbientGristHandshake, type GristWidgetSnapshot } from "grist-widget-sdk/advanced"
 
 import { deriveDisplayStatus, type HandshakeDisplayStatus } from "@/lib/grist-handshake-status"
 import { cn } from "@/lib/utils"
@@ -83,8 +83,7 @@ function ChipVisual({ display, secondsLeft }: { display: HandshakeDisplayStatus;
   }
 }
 
-function RealChipContents() {
-  const { snapshot } = useGristHandshakeContext()
+function RealChipContents({ snapshot }: { snapshot: GristWidgetSnapshot }) {
   const display = deriveDisplayStatus(snapshot.lifecycle)
   const retryAttempts = display.kind === "retrying" ? display.attempts : 0
   const secondsLeft = useRetryCountdown(retryAttempts, display.kind === "retrying")
@@ -93,25 +92,25 @@ function RealChipContents() {
 
 /**
  * Small pill showing live Grist handshake status while actually embedded in
- * Grist. Mounts its own `<GristHandshakeProvider>` alongside
- * `<GristWidgetProvider>` -- documented (grist-widget-sdk/advanced) as safe
- * to coexist, since both share the page's `ensureGristReady()` singleton.
- * Purely observational: it never drives the real widget's connection, just
- * reflects it.
+ * Grist. Must be mounted *inside* `<GristWidgetProvider>` -- it only observes
+ * that provider's own handshake manager (`useAmbientGristHandshake()`,
+ * `grist-widget-sdk/advanced`) and never mounts its own, so it can't ever run
+ * a second, competing `grist.ready()` call. Renders nothing outside a
+ * provider.
  */
 export function GristStatusChip({ className }: { className?: string }) {
+  const handshake = useAmbientGristHandshake()
+  if (!handshake) return null
   return (
-    <GristHandshakeProvider>
-      <div className="pointer-events-none fixed top-2 right-2 z-50">
-        <div
-          className={cn(
-            "flex items-center gap-1.5 rounded-full border bg-background/90 px-2.5 py-1 text-xs text-muted-foreground shadow-sm backdrop-blur",
-            className,
-          )}
-        >
-          <RealChipContents />
-        </div>
+    <div className="pointer-events-none fixed top-2 right-2 z-50">
+      <div
+        className={cn(
+          "flex items-center gap-1.5 rounded-full border bg-background/90 px-2.5 py-1 text-xs text-muted-foreground shadow-sm backdrop-blur",
+          className,
+        )}
+      >
+        <RealChipContents snapshot={handshake.snapshot} />
       </div>
-    </GristHandshakeProvider>
+    </div>
   )
 }

package/template/src/main.tsx

@@ -35,20 +35,18 @@ createRoot(document.getElementById("root")!).render(
           <TemplateLanding />
         </div>
       ) : isEmbedded ? (
-        <>
+        <GristWidgetProvider options={GRIST_OPTIONS}>
           <GristStatusChip />
-          <GristWidgetProvider options={GRIST_OPTIONS}>
-            <GristBoundary
-              gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}
-            >
-              <div className="min-h-full w-full bg-background text-foreground">
-                <GristSdkAlerts>
-                  <App />
-                </GristSdkAlerts>
-              </div>
-            </GristBoundary>
-          </GristWidgetProvider>
-        </>
+          <GristBoundary
+            gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}
+          >
+            <div className="min-h-full w-full bg-background text-foreground">
+              <GristSdkAlerts>
+                <App />
+              </GristSdkAlerts>
+            </div>
+          </GristBoundary>
+        </GristWidgetProvider>
       ) : (
         <div className="min-h-full w-full bg-background text-foreground">
           <ChannelNotice channel={channel} hubPath={hubPath} />