create-grist-widget 0.2.12 → 0.2.13

package/README.md

@@ -46,6 +46,11 @@ simplest way to get from zero to a deployed widget:
    folder `/ (root)`. This can only be set once `gh-pages` exists, which is
    why it's a step *after* the first push, not before.
 
+   > ⚠️ **Not `main`.** Pointing Pages at `main` serves this repo's raw,
+   > unbuilt source instead of the built site — the symptom is a blank page
+   > with a `/src/main.tsx` 404 in the browser console, even though the
+   > workflow itself reports success.
+
    Once that's saved, your widget is live at two URLs:
 
    - `https://<owner>.github.io/<repo>/latest/` — mutable, always points at

package/package.json

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

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

@@ -13,8 +13,11 @@ name: Deploy widget to GitHub Pages
 # One-time setup this workflow can't do for you: enable Pages (Settings ->
 # Pages -> Source: Deploy from a branch -> gh-pages -> / (root); this workflow
 # creates the gh-pages branch itself if missing, but Pages must be pointed at
-# it once) and make sure Actions has write access (Settings -> Actions ->
-# General -> Workflow permissions -> Read and write permissions).
+# it once -- NOT main, which serves this repo's raw unbuilt source instead
+# (symptom: a blank page with a 404 for /src/main.tsx in the browser
+# console, even though this workflow reports success) and make sure Actions
+# has write access (Settings -> Actions -> General -> Workflow permissions ->
+# Read and write permissions).
 
 on:
   push:
@@ -56,10 +59,16 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: pnpm
 
+      # Not --frozen-lockfile, and no `cache: pnpm` above: a freshly
+      # scaffolded repo never has a committed pnpm-lock.yaml (the CLI's
+      # auto-commit runs before anyone's first `pnpm install`), and
+      # --frozen-lockfile/cache: pnpm both hard-require one to exist —
+      # found live, the very first real deploy failed with "Dependencies
+      # lock file is not found". A plain install resolves fresh every run
+      # regardless of whether a lockfile was ever committed.
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install
 
       - name: Clone gh-pages into ./site
         run: |

package/template/README.md

@@ -92,6 +92,12 @@ automatically.
    → `/ (root)`. The workflow creates the `gh-pages` branch itself the first
    time it runs (if it doesn't exist yet), but Pages needs to be pointed at
    it once.
+   > ⚠️ **Not `main`.** If Pages is left on (or accidentally set to) `main`,
+   > it serves this repo's raw, unbuilt source — including a script tag
+   > pointing at `/src/main.tsx` — instead of the built site. The symptom is
+   > a blank/black page with a 404 for `/src/main.tsx` in the browser
+   > console, even though the workflow itself reports success (it pushed the
+   > right build to `gh-pages`; Pages is just reading from the wrong place).
 2. **Settings → Actions → General → Workflow permissions** → "Read and write
    permissions". New repos sometimes default the workflow's token to
    read-only, which would fail the push to `gh-pages` with a 403.

package/template/scripts/deploy.mjs

@@ -133,12 +133,22 @@ export function placeTarget({ siteDir, channel, version, distDir, sha, ref }) {
     }
     return { placed: "dev" }
   }
-  // release
+  // release: immutable v<version>/, mutable latest/, and the same build
+  // placed directly at the site root too. main.tsx renders the showcase hub
+  // (TemplateLanding) at any URL with no recognized channel suffix — the
+  // bare root included — so without this, a real scaffolded repo's own
+  // https://owner.github.io/repo/ has nothing deployed there at all and
+  // 404s instead of ever reaching that hub. Reusing the release dist here is
+  // exactly like latest/ reusing it: the asset URLs it references (under
+  // v<version>/assets/) already exist from the versionDir placement above,
+  // so nothing 404s.
   const versionDir = join(siteDir, `v${version}`)
   replaceDir(versionDir, distDir)
   const latestDir = join(siteDir, "latest")
   replaceDir(latestDir, distDir)
-  return { placed: `v${version}`, latest: "latest" }
+  mkdirSync(siteDir, { recursive: true })
+  cpSync(distDir, siteDir, { recursive: true })
+  return { placed: `v${version}`, latest: "latest", root: true }
 }
 
 /**

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

@@ -49,7 +49,7 @@ function StatusDot({ pulsing, className }: { pulsing: boolean; className: string
   )
 }
 
-/** Pure render of a display status -- shared by the real (context-driven) and demo (cycling) chips. */
+/** Pure render of a display status. */
 function ChipVisual({ display, secondsLeft }: { display: HandshakeDisplayStatus; secondsLeft: number }) {
   switch (display.kind) {
     case "connecting":
@@ -91,81 +91,27 @@ function RealChipContents() {
   return <ChipVisual display={display} secondsLeft={secondsLeft} />
 }
 
-// A fixed, looping sequence for the showcase hub -- there's no real Grist to
-// connect to on that page (it's shown precisely because a real widget isn't
-// embedded), so this is a cosmetic demo of the same visual states a real
-// widget's chip goes through, not a real handshake attempt.
-const DEMO_SEQUENCE: readonly { display: HandshakeDisplayStatus; ms: number }[] = [
-  { display: { kind: "connecting" }, ms: 1500 },
-  { display: { kind: "retrying", attempts: 1 }, ms: 3000 },
-  { display: { kind: "connected" }, ms: 3500 },
-]
-
-function DemoChipContents() {
-  const [step, setStep] = useState(0)
-  const [countdownState, setCountdownState] = useState({ step, secondsLeft: 3 })
-  const current = DEMO_SEQUENCE[step]
-
-  // Reset the mini countdown the moment the demo cycle enters "retrying" --
-  // an "adjust state during render" pattern, not a setState-in-effect.
-  if (current.display.kind === "retrying" && countdownState.step !== step) {
-    setCountdownState({ step, secondsLeft: 3 })
-  }
-
-  useEffect(() => {
-    const advance = setTimeout(() => {
-      setStep((s) => (s + 1) % DEMO_SEQUENCE.length)
-    }, current.ms)
-    return () => clearTimeout(advance)
-  }, [step, current.ms])
-
-  useEffect(() => {
-    if (current.display.kind !== "retrying") return
-    const id = setInterval(() => {
-      setCountdownState((s) => ({ ...s, secondsLeft: s.secondsLeft > 0 ? s.secondsLeft - 1 : 0 }))
-    }, 1000)
-    return () => clearInterval(id)
-  }, [step, current.display.kind])
-
-  return <ChipVisual display={current.display} secondsLeft={countdownState.secondsLeft} />
-}
-
 /**
- * Small pill showing Grist handshake status. Two modes:
- *
- * - Default: live 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.
- * - `demo`: a cosmetic, looping cycle through the same visual states, used
- *   on the showcase hub page where no real Grist connection is ever
- *   attempted -- a reference to the tech behind the template, not a status
- *   readout.
+ * 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.
  */
-export function GristStatusChip({
-  demo = false,
-  className,
-}: {
-  demo?: boolean
-  className?: string
-}) {
-  const pill = (
-    <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,
-      )}
-    >
-      {demo ? <DemoChipContents /> : <RealChipContents />}
-    </div>
-  )
-
-  if (demo) return pill
-
+export function GristStatusChip({ className }: { className?: string }) {
   return (
     <GristHandshakeProvider>
-      <div className="pointer-events-none fixed top-2 right-2 z-50">{pill}</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 />
+        </div>
+      </div>
     </GristHandshakeProvider>
   )
 }

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

@@ -1,6 +1,5 @@
 import { useState } from "react"
 
-import { GristStatusChip } from "@/components/grist-status-chip"
 import { Button } from "@/components/ui/button"
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
 import { DEV_URL, formatDate, useVersions, versionUrl } from "@/lib/showcase-versions"
@@ -70,9 +69,6 @@ export function TemplateLanding() {
   return (
     <div className="mx-auto max-w-2xl px-6 py-16">
       <header className="mb-10 text-center">
-        <div className="mb-4 flex justify-center">
-          <GristStatusChip demo />
-        </div>
         <p className="mb-2 text-sm font-medium text-muted-foreground">
           grist-widget-template
         </p>
@@ -157,6 +153,13 @@ git push origin dev`}</code>
                 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