@pantheon-systems/create-p1-starter-kit 0.12.0 → 0.13.0

package/template/app/[...puckPath]/client.tsx

@@ -2,8 +2,9 @@
 
 import { useEffect, useState } from "react";
 import type { Data } from "@puckeditor/core";
-import { RenderClient } from "@pantheon-systems/puck-css";
+import { RenderClient, performLogout, P1_LOGGED_IN_KEY } from "@pantheon-systems/puck-css";
 import config from "../../puck.config";
+import { runWidgetLogout } from "./widget-logout";
 
 function EditIcon() {
   return (
@@ -35,10 +36,12 @@ function LogoutIcon() {
 export function P1EditWidget({ route }: { route: string }) {
   const [hasToken, setHasToken] = useState(false);
   const [open, setOpen] = useState(false);
+  const [isLoggingOut, setIsLoggingOut] = useState(false);
+  const [logoutError, setLogoutError] = useState<string | null>(null);
 
   useEffect(() => {
     const flag = typeof localStorage !== "undefined"
-      ? localStorage.getItem("p1_logged_in")
+      ? localStorage.getItem(P1_LOGGED_IN_KEY)
       : null;
     setHasToken(!!flag);
   }, []);
@@ -63,6 +66,22 @@ export function P1EditWidget({ route }: { route: string }) {
 
   const editHref = `/p1${route === "/" ? "" : route}`;
 
+  const handleLogout = () =>
+    runWidgetLogout({
+      logout: () =>
+        performLogout({
+          cssBaseUrl: process.env.NEXT_PUBLIC_CSS_BASE_URL ?? "http://localhost:8787",
+        }),
+      navigate: (url) => {
+        window.location.href = url;
+      },
+      reload: () => {
+        window.location.reload();
+      },
+      setBusy: setIsLoggingOut,
+      setError: setLogoutError,
+    });
+
   return (
     <div
       data-p1-widget
@@ -145,12 +164,8 @@ export function P1EditWidget({ route }: { route: string }) {
           <div style={{ height: 1, background: "#e0e0e0", margin: "6px 4px" }} />
           <button
             role="menuitem"
-            onClick={() => {
-              localStorage.removeItem("p1_logged_in");
-              localStorage.removeItem("p1_auth_token");
-              localStorage.removeItem("css_broker_token");
-              window.location.reload();
-            }}
+            disabled={isLoggingOut}
+            onClick={handleLogout}
             style={{
               display: "flex",
               alignItems: "center",
@@ -163,15 +178,28 @@ export function P1EditWidget({ route }: { route: string }) {
               textDecoration: "none",
               background: "transparent",
               border: "none",
-              cursor: "pointer",
+              cursor: isLoggingOut ? "not-allowed" : "pointer",
               fontFamily: "inherit",
             }}
             onMouseEnter={(e) => { e.currentTarget.style.background = "#f5f5f5"; }}
             onMouseLeave={(e) => { e.currentTarget.style.background = "transparent"; }}
           >
             <span style={{ color: "#888", flex: "0 0 auto" }}><LogoutIcon /></span>
-            Log out
+            {isLoggingOut ? "Logging out…" : "Log out"}
           </button>
+          {logoutError && (
+            <p
+              role="alert"
+              style={{
+                margin: "2px 10px 6px",
+                fontSize: 12,
+                lineHeight: 1.4,
+                color: "#b3261e",
+              }}
+            >
+              {logoutError}
+            </p>
+          )}
         </div>
       )}
     </div>

package/template/app/[...puckPath]/page.tsx

@@ -21,7 +21,7 @@ import { ContentUnavailable } from "../../components/content-unavailable";
 import { resolvePageMetadata } from "../../lib/page-seo";
 import { Client } from "./client";
 
-const getCssQueryFetchers = cache(() => createCssQueryFetchers());
+const getCcrQueryFetchers = cache(() => createCssQueryFetchers());
 
 // Document namespaces that live alongside pages but are never routable.
 const INTERNAL_PATH_PREFIXES = ["/_registry", "/_redirects"];
@@ -101,11 +101,11 @@ export default async function Page({
 
   const data = result.data;
 
-  const [routeTemplateKeys, cssQueryFetchers] = await Promise.all([
+  const [routeTemplateKeys, ccrQueryFetchers] = await Promise.all([
     loadRouteTemplateKeys(),
-    getCssQueryFetchers(),
+    getCcrQueryFetchers(),
   ]);
-  const builtinFetchers = [...REMOTE_DATASOURCE_FETCHERS, ...cssQueryFetchers];
+  const builtinFetchers = [...REMOTE_DATASOURCE_FETCHERS, ...ccrQueryFetchers];
 
   const referencedDatasourceIds = extractReferencedDatasourceIds(data);
   const context = await loadRemoteDatasourceContext({

package/template/app/[...puckPath]/widget-logout.ts

@@ -0,0 +1,36 @@
+import type { LogoutOutcome } from "@pantheon-systems/puck-css";
+
+export type WidgetLogoutEffects = {
+  logout: () => Promise<LogoutOutcome>;
+  navigate: (url: string) => void;
+  reload: () => void;
+  setBusy: (busy: boolean) => void;
+  setError: (message: string | null) => void;
+};
+
+/**
+ * Runs one logout attempt for the widget. Kept outside the component so each
+ * outcome — navigate away, stay and explain, reload — can be exercised without
+ * a browser.
+ */
+export async function runWidgetLogout(fx: WidgetLogoutEffects): Promise<void> {
+  fx.setBusy(true);
+  fx.setError(null);
+  try {
+    const outcome = await fx.logout();
+    if (outcome.status === "signed_out") {
+      fx.navigate(outcome.logoutUrl);
+      return; // navigation takes over
+    }
+    if (outcome.status === "error") {
+      // Still signed in and retryable — keep the menu open and say why.
+      fx.setError(outcome.message);
+      fx.setBusy(false);
+      return;
+    }
+    fx.reload(); // no_session: drop any stale widget state
+  } catch (err) {
+    fx.setError(err instanceof Error ? err.message : "Logout failed");
+    fx.setBusy(false);
+  }
+}

package/template/app/p1/(editor)/[[...p1]]/editor-client.tsx

@@ -14,6 +14,7 @@ import {
   wrapConfigForEditorPreview,
   P1QueryProvider,
   editorPathHref,
+  EditorReloadOverlay,
 } from "@pantheon-systems/puck-css";
 import { DatasourceRegistryProvider, DatasourceDataProvider } from "@pantheon-systems/puck-css/fields";
 import { LoadingMessage } from "@pantheon-systems/puck-css/pds";
@@ -120,7 +121,6 @@ export function EditorClientWrapper() {
   const pathname = usePathname();
   const path = editorPagePathFromUrlPath(pathname);
   const [userRole, setUserRole] = useState<ContentRole>('editor');
-  const lastGoodStateRef = React.useRef<{ puckKey: string; puckProps: any } | null>(null);
 
   if (!p1Config) {
     return (
@@ -145,7 +145,7 @@ export function EditorClientWrapper() {
           loginFallback={<P1SignInPage />}
         >
           <ChatbotFlagProvider>
-            <EditorContent path={path} lastGoodStateRef={lastGoodStateRef} />
+            <EditorContent path={path} />
           </ChatbotFlagProvider>
         </P1App>
         {process.env.NEXT_PUBLIC_ENABLE_ROLE_SWITCHER === 'true' && (
@@ -206,13 +206,7 @@ function RoleSwitcher({
   );
 }
 
-function EditorContent({
-  path,
-  lastGoodStateRef,
-}: {
-  path: string;
-  lastGoodStateRef: React.MutableRefObject<{ puckKey: string; puckProps: any } | null>;
-}) {
+function EditorContent({ path }: { path: string }) {
   const router = useRouter();
   const { getToken } = useP1Auth();
   const { data: editorCtx } = useEditorContext(path);
@@ -280,7 +274,7 @@ function EditorContent({
     [getToken],
   );
 
-  const { loading, error, puckKey, puckProps } = useP1Editor({
+  const { loading, reloading, hasContent, error, puckKey, puckProps } = useP1Editor({
     documentPath: path,
     puckConfig: editorConfig,
     additionalPlugins,
@@ -305,24 +299,17 @@ function EditorContent({
     },
   });
 
-  // Update last good state when loading completes successfully (ref passed from parent)
-  React.useEffect(() => {
-    if (!loading && !error) {
-      lastGoodStateRef.current = { puckKey, puckProps };
-    }
-  }, [loading, error, puckKey, puckProps]);
-
   if (redirecting) {
     return <LoadingMessage message="Redirecting" data-testid="editor-redirecting" />;
   }
 
-  // Show full loading screen only on first load (no previous state)
-  if (loading && !lastGoodStateRef.current) {
+  if (loading) {
     return <LoadingMessage message="Loading document" data-testid="editor-loading" />;
   }
 
-  // Show error only if we have no previous state to fall back to
-  if (error && !lastGoodStateRef.current) {
+  // A failed load with a document already on screen keeps that document; only a
+  // failure with nothing to fall back on takes over the view.
+  if (error && !hasContent) {
     return (
       <div style={{ textAlign: "center", padding: "4rem", fontFamily: "system-ui" }}>
         <h3>Error loading document</h3>
@@ -331,57 +318,13 @@ function EditorContent({
     );
   }
 
-  // Use current state if loaded, otherwise keep showing last good state
-  const displayState = (!loading && !error)
-    ? { puckKey, puckProps }
-    : lastGoodStateRef.current ?? { puckKey, puckProps };
-
   return (
     <div className="puck-editor-theme" style={{ position: "relative" }}>
-      {/* Loading overlay - shown during branch switch */}
-      {loading && lastGoodStateRef.current && (
-        <div
-          style={{
-            position: "fixed",
-            top: "50%",
-            left: "50%",
-            transform: "translate(-50%, -50%)",
-            zIndex: 9999,
-            background: "rgba(255, 255, 255, 0.95)",
-            padding: "1rem 2rem",
-            borderRadius: "8px",
-            boxShadow: "0 4px 12px rgba(0, 0, 0, 0.15)",
-            fontFamily: "system-ui",
-            fontSize: "14px",
-            color: "#333",
-            fontWeight: 500,
-            display: "flex",
-            alignItems: "center",
-            gap: "0.75rem",
-          }}
-        >
-          <div
-            style={{
-              width: "16px",
-              height: "16px",
-              border: "2px solid #e0e0e0",
-              borderTopColor: "#2563eb",
-              borderRadius: "50%",
-              animation: "spin 0.6s linear infinite",
-            }}
-          />
-          Switching workstream...
-          <style>{`
-            @keyframes spin {
-              to { transform: rotate(360deg); }
-            }
-          `}</style>
-        </div>
-      )}
+      <EditorReloadOverlay reloading={reloading} />
       <DatasourceRegistryProvider registry={editorCtx?.remoteDatasourceRegistry ?? []}>
         <DatasourceDataProvider context={remoteDatasourceContext}>
           {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
-          <Puck key={`${displayState.puckKey}-${chatbotEnabled ? "ai" : "no-ai"}`} {...displayState.puckProps as any} _experimentalFullScreenCanvas={true} />
+          <Puck key={`${puckKey}-${chatbotEnabled ? "ai" : "no-ai"}`} {...puckProps as any} _experimentalFullScreenCanvas={true} />
         </DatasourceDataProvider>
       </DatasourceRegistryProvider>
     </div>

package/template/app/styles.css

@@ -7,7 +7,7 @@
 @source "../node_modules/@pantheon-systems/puck-css/dist";
 
 /* Scoped via :has() rather than a bare `body {...}` selector so this reset
-   stays out of Puck's canvas-preview iframe (PCC-3499 / PCC-3513).
+   stays out of Puck's canvas-preview iframe.
    Puck's collectStyles() copies every parent <style>/<link> into the canvas
    iframe verbatim (querySelectorAll('style, link[rel="stylesheet"]'), no
    exclusion API) — so a bare `body {...}` rule here would also match inside

package/template/ci-examples/github-actions-sync-puck-registry.yml

@@ -1,4 +1,4 @@
-# Optional: syncs this site's Puck component registry to the CSS backend
+# Optional: syncs this site's Puck component registry to the backend
 # headlessly on every push, without anyone needing to open the editor.
 #
 # This file is NOT active until you copy it into .github/workflows/ yourself
@@ -12,11 +12,12 @@
 #   3. Copy this file to .github/workflows/sync-puck-registry.yml.
 #
 # Triggers on push to any branch that touches puck.config.tsx or
-# components/puck/**. The sync script resolves the CSS branch from the pushed
-# git branch's name: the repo's default branch always targets the site's main
-# CSS branch (whatever the git branch is called), any other ref matches a CSS
-# branch by name. A push on a non-default branch with no matching CSS branch
-# is not an error: the script logs a skip and exits 0.
+# components/puck/**. The sync script resolves the target branch from the
+# pushed git branch's name: the repo's default branch always targets the
+# site's main branch (whatever the git branch is called), any other ref
+# matches a branch on the site by name. A push on a non-default branch with
+# no matching branch on the site is not an error: the script logs a skip and
+# exits 0.
 #
 # CSS_DEFAULT_BRANCH defaults to "main" if omitted — repos whose default
 # branch has another name (master, trunk) need the line below (or must set
@@ -33,10 +34,17 @@ on:
   workflow_dispatch:
     inputs:
       branch_id:
-        description: 'CSS branch ID/name to sync against (blank = match the current git branch, else site main)'
+        description: 'Branch ID/name to sync against (blank = match the current git branch, else site main)'
         required: false
         default: ''
 
+# A branch pushed several times in quick succession only needs its newest
+# component set synced. Without this, every push starts its own run and they
+# race each other into the same registry documents.
+concurrency:
+  group: sync-puck-registry-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   sync-registry:
     runs-on: ubuntu-latest

package/template/eslint.config.js

@@ -6,7 +6,31 @@ import react from 'eslint-plugin-react';
 import reactHooks from 'eslint-plugin-react-hooks';
 import prettierConfig from 'eslint-config-prettier';
 
+/**
+ * Test-file relaxations.
+ *
+ * Append this AFTER the base/react/worker layers so it wins. Each rule here is
+ * off because the pattern it flags is idiomatic in tests, not debt — measured
+ * against the repo on 2026-08-05, where 79% of no-non-null-assertion and 77% of
+ * no-empty-function findings were in test files.
+ *
+ * Rules deliberately NOT relaxed: no-floating-promises and no-misused-promises
+ * (an unawaited promise in a test is a silently passing test),
+ * no-unnecessary-condition (it found real dead assertions), and no-unused-vars.
+ */
+
+const TEST_FILES = [
+  '**/*.{test,spec}.{js,jsx,mjs,cjs,ts,tsx}',
+  '**/tests/**/*.{js,jsx,mjs,cjs,ts,tsx}',
+  '**/test/**/*.{js,jsx,mjs,cjs,ts,tsx}',
+  '**/__tests__/**/*.{js,jsx,mjs,cjs,ts,tsx}',
+  '**/__mocks__/**/*.{js,jsx,mjs,cjs,ts,tsx}',
+  '**/test-stubs/**/*.{js,jsx,mjs,cjs,ts,tsx}',
+  '**/*.setup.{js,mjs,cjs,ts}',
+];
+
 export default tseslint.config(
+  // @pantheon-systems/eslint-config/base
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
   ...tseslint.configs.strict,
@@ -42,12 +66,14 @@ export default tseslint.config(
       '@typescript-eslint/consistent-type-imports': 'warn',
       '@typescript-eslint/explicit-function-return-type': 'off',
       '@typescript-eslint/explicit-module-boundary-types': 'off',
+
       // Import rules
       'import/extensions': 'off',
       'import/prefer-default-export': 'off',
       'import/no-unresolved': 'off',
       'import/order': 'warn',
       'import/no-extraneous-dependencies': 'warn',
+
       // General ESLint rules
       'no-console': 'off',
       'no-debugger': 'error',
@@ -75,6 +101,7 @@ export default tseslint.config(
           ],
         },
       ],
+
       // Stricter rules (warn to resolve over time)
       '@typescript-eslint/consistent-generic-constructors': 'warn',
       '@typescript-eslint/consistent-indexed-object-style': 'warn',
@@ -146,6 +173,7 @@ export default tseslint.config(
       '**/.puppeteerrc.cjs',
     ],
   },
+  // @pantheon-systems/eslint-config/react
   {
     files: ['**/*.{ts,tsx,jsx}'],
     plugins: {
@@ -173,5 +201,40 @@ export default tseslint.config(
       'react-hooks/exhaustive-deps': 'warn',
     },
   },
+  // @pantheon-systems/eslint-config/prettier
   prettierConfig,
+  // @pantheon-systems/eslint-config/tests
+  {
+    files: TEST_FILES,
+    rules: {
+      // `x!` after a known-good arrange step asserts the fixture, it doesn't hide a bug.
+      '@typescript-eslint/no-non-null-assertion': 'off',
+      // `() => {}` is the entire point of a stub.
+      '@typescript-eslint/no-empty-function': 'off',
+      // Passing an unbound method to vi.spyOn / expect is the documented API.
+      '@typescript-eslint/unbound-method': 'off',
+      // Test helpers are read at the call site; annotating their returns is noise.
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      // `async` with no await is how you satisfy an interface in a fake.
+      '@typescript-eslint/require-await': 'off',
+      // Mock payloads are structurally untyped by nature.
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/no-useless-constructor': 'off',
+      // Stand-ins for `cloudflare:*` built-ins have to be classes to stand in
+      // for classes, even with nothing in them.
+      '@typescript-eslint/no-extraneous-class': 'off',
+      // `vi.importActual<typeof import('mod')>('mod')` is vitest's documented
+      // shape and cannot be hoisted to a top-level type import.
+      '@typescript-eslint/consistent-type-imports': ['warn', { disallowTypeAnnotations: false }],
+      // Inline fixtures and assertion chains run long. The formatter will own
+      // line length once it lands; until then this is the only rule that would
+      // force hand-wrapping code a formatter is about to rewrite.
+      'max-len': 'off',
+    },
+  },
 );

package/template/gitignore

@@ -0,0 +1,43 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+.claude/
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.env
+!.env.example
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel

package/template/lib/chatbot-flag/ai-generate.ts

@@ -6,7 +6,7 @@ import type { DraftRequestChannel } from "@pantheon-systems/p1-ai-chat";
  *
  * The page does not exist yet: the chat proposes the page template it should start from and
  * creates it once the user agrees, because a document's template can only be set as it is
- * created (PCC-3555). Until then the request carries the title and path the dialog collected.
+ * created. Until then the request carries the title and path the dialog collected.
  */
 export function createGenerateWithAIHandler(
   draftRequests: DraftRequestChannel,

package/template/lib/page-seo.ts

@@ -37,7 +37,7 @@ const carriesTemplate = (value: unknown): value is string =>
   typeof value === "string" && value.includes("{{");
 
 /**
- * Produces the per-page <head> Metadata for a route (PCC-3407). Title,
+ * Produces the per-page <head> Metadata for a route. Title,
  * description and the free-text metadata fields are template-allowed.
  */
 export async function resolvePageMetadata({

package/template/package.json

@@ -15,12 +15,12 @@
   },
   "dependencies": {
     "@pantheon-systems/cpub-react-sdk": "^5.2.1",
-    "@pantheon-systems/css-client": "^0.12.0",
-    "@pantheon-systems/p1-ai-chat": "^0.5.1",
-    "@pantheon-systems/p1-media": "^0.4.4",
-    "@pantheon-systems/p1-next-sdk": "^0.12.0",
+    "@pantheon-systems/css-client": "^0.13.0",
+    "@pantheon-systems/p1-ai-chat": "^0.6.0",
+    "@pantheon-systems/p1-media": "^0.4.5",
+    "@pantheon-systems/p1-next-sdk": "^0.13.0",
     "@pantheon-systems/pds-toolkit-react": "2.0.0-alpha.66",
-    "@pantheon-systems/puck-css": "^0.12.0",
+    "@pantheon-systems/puck-css": "^0.13.0",
     "@puckeditor/core": "^0.21.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/typography": "^0.5.16",

package/template/scripts/__tests__/sync-puck-registry.test.ts

@@ -56,7 +56,7 @@ describe("validateEnv", () => {
   });
 
   it("defaults defaultBranchName to 'main' when CSS_DEFAULT_BRANCH is not set", () => {
-    // Safe because the CSS main content branch is always literally named
+    // Safe because the site's main content branch is always literally named
     // "main": a push override of "main" resolves to the same branch either
     // by name match or by isMain, so the default only adds semantics.
     const result = validateEnv(baseEnv());
@@ -145,8 +145,8 @@ describe("resolveBranchId", () => {
 
 describe("resolveBranchId default-branch semantics", () => {
   // In CI the override is always the pushed git ref's name, so a repo whose
-  // default branch is not literally named "main" would never match the CSS
-  // main branch (whose name is always "main") — the sync silently skips on
+  // default branch is not literally named "main" would never match the
+  // site's main branch (whose name is always "main") — the sync silently skips on
   // every default-branch push. When the caller also supplies the repo's
   // default branch name, an override equal to it must resolve via isMain.
   const branches = [

package/template/scripts/sync-puck-registry.ts

@@ -2,23 +2,23 @@
  * Syncs this site's Puck component registry (_registry/components/* and the
  * registry index) headlessly, without opening the editor in a browser.
  * Intended to run from CI on push to main or a branch whose name matches a
- * CSS branch, whenever puck.config.tsx or components/puck/** change.
+ * branch on the site, whenever puck.config.tsx or components/puck/** change.
  *
  * Usage: tsx scripts/sync-puck-registry.ts [--dry-run]
  *
  * Required env vars (see validateEnv below for the full fallback contract):
  *   CSS_BASE_URL, CSS_SITE_ID, CSS_REGISTRY_API_KEY
  * Optional:
- *   CSS_BRANCH_ID — CSS branch to target (in CI: the pushed git ref's name)
+ *   CSS_BRANCH_ID — branch to target (in CI: the pushed git ref's name)
  *   CSS_DEFAULT_BRANCH — the repo's default branch name (defaults to "main");
  *   when CSS_BRANCH_ID equals it, the site's isMain branch is targeted
  *   regardless of naming (see resolveBranchId for the resolution contract)
  *
  * CSS_REGISTRY_API_KEY must be a sat_ site token scoped to write:registry
  * only — do not reuse a read-scoped token (P1_CSS_API_KEY). Because that
- * token has no read access at all, every run rewrites every component
- * descriptor + the registry index unconditionally (no skip-if-unchanged) —
- * see syncComponentRegistryWriteOnly.
+ * token has no read access at all, every run posts every component
+ * descriptor + the registry index; the backend compares each against stored
+ * content and writes only what changed — see syncComponentRegistryWriteOnly.
  */
 
 import { register } from "node:module";
@@ -43,7 +43,7 @@ export function validateEnv(env: Record<string, string | undefined>): ValidatedE
   const siteId = env.CSS_SITE_ID ?? env.NEXT_PUBLIC_CSS_SITE_ID;
   const apiKey = env.CSS_REGISTRY_API_KEY;
   const branchOverride = env.CSS_BRANCH_ID ?? env.NEXT_PUBLIC_CSS_BRANCH_ID;
-  // Defaults to "main": the CSS main content branch is always literally
+  // Defaults to "main": the site's main content branch is always literally
   // named "main", so for repos whose default git branch is also "main" this
   // resolves to the same branch it would have matched by name. Repos with a
   // differently-named default branch (master, trunk) must set it explicitly.
@@ -88,10 +88,10 @@ export function resolveConfigModule(mod: unknown): unknown {
 }
 
 /**
- * Thrown by resolveBranchId when no CSS branch matches. Distinguished from
- * other errors so callers (main(), a CI trigger firing on every git branch)
- * can treat "this branch has no CSS counterpart" as a benign no-op rather
- * than a real sync failure.
+ * Thrown by resolveBranchId when no matching branch is found. Distinguished
+ * from other errors so callers (main(), a CI trigger firing on every git
+ * branch) can treat "this branch has no counterpart on the site" as a benign
+ * no-op rather than a real sync failure.
  */
 export class NoBranchMatchError extends Error {}
 
@@ -133,12 +133,12 @@ export function filterAssetStubbedDescriptors(descriptors: Descriptor[]): {
 
 /**
  * Resolution contract: an override (in CI, always the pushed git ref's name)
- * matches a CSS branch by id or name — EXCEPT when it equals the repo's
- * default branch name, which always resolves the site's isMain branch. CSS
- * main is always literally named "main", so without that rule a repo whose
- * default branch is "master"/"trunk" would silently skip on every push. The
- * default branch means the main registry, even over a coincidental CSS
- * branch named e.g. "master".
+ * matches a branch on the site by id or name — EXCEPT when it equals the
+ * repo's default branch name, which always resolves the site's isMain
+ * branch. The site's main branch is always literally named "main", so
+ * without that rule a repo whose default branch is "master"/"trunk" would
+ * silently skip on every push. The default branch means the main registry,
+ * even over a coincidentally-named branch on the site, e.g. "master".
  */
 export function resolveBranchId(
   branches: Branch[],
@@ -211,8 +211,8 @@ const isMainModule = import.meta.url === pathToFileURL(process.argv[1] ?? "").hr
 if (isMainModule) {
   main().catch((err: unknown) => {
     // A CI trigger firing on every git branch push has no way to know ahead
-    // of time which branches have a matching CSS branch — that has to be
-    // discovered at runtime. Treat "no match" as a benign no-op, not a
+    // of time which branches have a matching branch on the site — that has
+    // to be discovered at runtime. Treat "no match" as a benign no-op, not a
     // failure, so unrelated feature-branch pushes don't turn CI red.
     if (err instanceof NoBranchMatchError) {
       console.log(`[sync-puck-registry] Skipping: ${err.message}`);