create-nextblock 0.15.0 → 0.15.2

package/templates/nextblock-template/app/cms/settings/site-scripts/components/SiteScriptManager.tsx

@@ -184,14 +184,22 @@ function ScriptEditor({
           page's CSP nonce.
         </p>
         <p className="text-xs text-muted-foreground">
-          Pages are React-hydrated. If your script changes text, classes, or attributes of existing
-          markup, wait for hydration or React will discard and re-render that part of the page:
+          Pages are React-hydrated. Do <strong>not</strong> change the text, classes, or attributes
+          of existing markup — React reconciles afterwards and reverts your change (a counter
+          animates, then snaps back). Waiting for the <code>load</code> event is not enough;
+          hydration can still be running. Animate with the Web Animations API instead, which writes
+          no attributes:
         </p>
         <pre className="overflow-x-auto rounded-md bg-muted p-3 text-xs">
-          <code>{`function run() { /* your DOM code */ }
-if (document.readyState === 'complete') run();
-else window.addEventListener('load', run);`}</code>
+          <code>{`el.animate(
+  [{ opacity: 0 }, { opacity: 1 }],
+  { duration: 600, fill: 'both' }
+);`}</code>
         </pre>
+        <p className="text-xs text-muted-foreground">
+          Appending your own new elements is always safe — React does not own those. So is anything
+          you can express in CSS.
+        </p>
       </div>
 
       <div className="grid gap-4 sm:grid-cols-2">

package/templates/nextblock-template/docs/04-DATABASE-AND-AUTH.md

@@ -104,7 +104,8 @@ Defined primarily in `00000000000002_setup_content_tables.sql`:
 
 ### Commerce tables
 
-Defined across `00000000000003` and `00000000000004`:
+All defined in the baseline schema `00000000000000` (the numbers `00000000000003`/
+`00000000000004` in earlier revisions of this doc were pre-re-baseline file names):
 
 - `products`
 - `product_media`

package/templates/nextblock-template/docs/08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md

@@ -1561,8 +1561,8 @@ When modifying Cortex AI, keep these invariants:
 15. A substituted actor identity is for attribution only, never authorization.
 16. The audit log for site scripts is append-only in the database. Reverting writes a
     new revision; it never removes one.
-17. Inline scripts in block HTML need the CSP nonce, and must wait for hydration
-    before touching server-rendered DOM.
+17. Inline scripts in block HTML need the CSP nonce, and must not mutate
+    server-rendered DOM at all — `load` is not a post-hydration signal.
 
 ## MCP Server: Security Model and Operator Guide
 
@@ -1638,15 +1638,30 @@ The site CSP carries a nonce, and per CSP Level 2 a browser **ignores
   authorized regardless of the CSP host allowlist. That is inherent to the feature
   and a reason it is ADMIN-only.
 
-Author scripts must also not fight React hydration: a script that changes text,
-classes, or attributes of server-rendered markup before hydration makes the client
-disagree with the SSR HTML and React discards that subtree. Wrap DOM work as:
-
-```js
-function run() { /* ... */ }
-if (document.readyState === 'complete') run();
-else window.addEventListener('load', run);
-```
+### Author scripts and React hydration
+
+Public pages are React-hydrated, and this is the single most common way an author
+script goes wrong. **Do not change the text, classes, or attributes of
+server-rendered markup.** React reconciles after the script runs and either reverts
+the change or logs a hydration mismatch — a counter visibly animates and then snaps
+back to its server value.
+
+Waiting for the `load` event is **not** a fix. With streaming and selective
+hydration, hydration can still be in flight when `load` fires; this was tried and
+still produced mismatches on `<section className=…>`.
+
+Patterns that are actually safe:
+
+- **Web Animations API.** `el.animate([...], {fill: 'both'})` creates an Animation
+  object and writes neither `class` nor `style`, so React has nothing to diff. A
+  paused animation held at `currentTime = 0` hides an element without a class.
+- **Append your own elements.** React does not own what the script creates, so a
+  progress bar or overlay appended to `<body>` is unconditionally safe.
+- **CSS.** Anything expressible in CSS carries no hydration risk at all.
+- **If text must change**, render the FINAL value server-side and animate toward it
+  once the element scrolls into view, so any reconciliation lands on the correct
+  value rather than resetting the animation. Format numbers with a fixed formatter,
+  not `toLocaleString()`, so the client string matches the server byte for byte.
 
 ### SSRF
 

package/templates/nextblock-template/docs/11-SELF-HOSTED-DOCKER.md

@@ -95,6 +95,15 @@ Both named volumes persist your database and uploaded media across restarts.
 | `npm run docker:up` | Rebuild and (re)start the stack. |
 | `npm run docker:down` | Stop the stack. Add `-v` to also delete the volumes (wipes local data). |
 | `npm run docker:logs` | Follow the app logs (`docker compose logs -f nextblock-cms`). |
+| `npm run update` | Update the app, its dependencies and the staged migration SQL. Follow it with `docker:up`, which is what applies the migrations — see below. |
+
+> **Updating a Docker install: `npm run update` then `npm run docker:up`.** The updater
+> deliberately does *not* apply migrations here. This stack ships its own migration runner
+> (the `migrate` service, which mounts `supabase/migrations` and records applied versions in
+> `public._nextblock_docker_migrations` — a different tracker from the one every other
+> install uses), so applying the same SQL from the updater as well would run it through two
+> trackers. The updater refreshes the SQL on disk and hands the schema step to the stack.
+> Full details in [docs/13](./13-STAYING-UP-TO-DATE.md).
 
 ### Ports (override with env vars)
 

package/templates/nextblock-template/docs/12-VERCEL-DEPLOYMENT.md

@@ -168,3 +168,11 @@ zero-config); a **private** repo additionally needs a `NEXTBLOCK_GITHUB_TOKEN` e
 the in-CMS conflict banner. (Only a *manually-created GitHub fork* has Actions disabled
 until you enable them on the Actions tab.) Full details — both tracks, conflict handling,
 and build-time migrations — are in [docs/13](./13-STAYING-UP-TO-DATE.md).
+
+> **This applies to the 1-click deploy specifically, not to "anything on Vercel".** The
+> sync workflow merges the NextBlock **monorepo** into your repository, so it only works
+> where your repository *is* that monorepo — a 1-click deploy, a GitHub fork, or a clone. A
+> project created with `npm create nextblock` is the flattened standalone app; deploying it
+> to Vercel does not change its shape, and NextBlock deliberately does not offer it the
+> workflow (merging `apps/`, `libs/` and `nx.json` into it would wreck it). That kind of
+> install updates with `npm run update` — see [docs/13](./13-STAYING-UP-TO-DATE.md).