create-nextblock 0.15.8 → 0.15.9

package/templates/nextblock-template/components/commerce/PaymentReadinessBoundary.tsx

@@ -0,0 +1,32 @@
+import { getStoreReadiness } from '@nextblock-cms/ecommerce/server';
+import { PaymentReadinessProvider } from '@nextblock-cms/ecommerce/PaymentReadinessProvider';
+
+/**
+ * Supplies payment readiness to the buy controls beneath it.
+ *
+ * Deliberately NOT mounted in the root layout: readiness is only consulted by buy CTAs
+ * and the checkout, so a blog post or a landing page should not pay for the lookup. Each
+ * commerce block renderer wraps itself in this instead, which also means nested cases
+ * (a product grid inside a section) are covered without anyone having to walk the block
+ * tree looking for them.
+ *
+ * getStoreReadiness() is request-cached, so several of these on one page cost one read.
+ * Any failure yields no readiness at all, and the context default ("everything ready")
+ * keeps a working store working.
+ */
+export default async function PaymentReadinessBoundary({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  let readiness: { stripe: boolean; freemius: boolean } | null = null;
+
+  try {
+    const store = await getStoreReadiness();
+    readiness = { stripe: store.stripe.ready, freemius: store.freemius.ready };
+  } catch (error) {
+    console.error('[PaymentReadinessBoundary] Could not resolve payment readiness:', error);
+  }
+
+  return <PaymentReadinessProvider readiness={readiness}>{children}</PaymentReadinessProvider>;
+}

package/templates/nextblock-template/docs/14-MESSAGES-INBOX.md

@@ -0,0 +1,309 @@
+# 14 · Messages — the unified inbox
+
+Everything a visitor sends the site arrives in one place: **CMS → Messages**
+(`/cms/messages`). Four sources feed it, and the admin can reply to all of them from
+there.
+
+The inbox is one *view* over **two storage models**, because the sources are genuinely
+different and flattening them would break something real.
+
+| Source | Table | Visibility | What a reply is |
+|---|---|---|---|
+| Product enquiry | `message_threads` + `thread_messages` | private | a private message, delivered via a tokenised link |
+| Contact form | `message_threads` + `thread_messages` | private | same |
+| Product review | `cms_interactions` | already public | a **public** reply under the review |
+| Post comment | `cms_interactions` | already public | a **public** reply under the comment |
+
+`app/cms/messages/loadInbox.ts` performs the merge in the read path and normalises both
+into an `InboxItem`. The detail pane branches on `item.kind`.
+
+## Why not one table
+
+`cms_interactions` cannot hold an enquiry, and the reasons are all enforced by the
+schema rather than by convention:
+
+- `user_id` is `NOT NULL` with a foreign key to `profiles` — every review and comment
+  belongs to a registered account. Enquiry senders are anonymous.
+- `check_product_or_post` requires *exactly one* of `product_id` / `post_id`. A contact
+  form targets neither.
+- Reviews and comments are readable by `anon` through an open `SELECT` policy once
+  approved. Enquiries carry visitor PII and have **no anon grant or policy at all**.
+- `update_product_ratings()` fires on every `cms_interactions` write.
+
+That last point is the sharp edge. The trigger aggregates
+`WHERE product_id = ? AND type='review' AND status='approved'`, so anything stored as an
+approved review moves the product's star average. **A staff reply is therefore stored as
+`type='comment'` with a NULL rating**, carrying the parent's target. That is not a
+workaround for convenience — `check_rating_only_for_review` is an exhaustive `OR` over
+`('review','comment')`, so a `review` row with a NULL rating is rejected outright, and
+adding a third enum value would violate the same constraint *and* hit PostgreSQL's rule
+that an enum value cannot be used in the transaction that added it (i.e. in one
+migration file). `cms_interactions_reply_check` pins the invariant in the schema.
+
+## The private lane
+
+`message_threads` is the spine; `thread_messages` holds the turns. Message *content* is
+append-only, enforced by a trigger that binds the service role too — only the delivery
+flags may change after insert. A consequence worth knowing: because the foreign key
+cascades and the trigger blocks `DELETE`, **a thread cannot be deleted**. "Delete" in
+the CMS means `status='closed'` plus a revoked token.
+
+### The visitor's token
+
+The only opaque credential this codebase issues to an anonymous person.
+
+- 32 bytes of `crypto.randomBytes`, prefixed `nbt_`. Guessing is infeasible by
+  keyspace, which matters because the GET has no rate limit.
+- Only `sha256` is stored, in `message_threads.token_hash` under a unique index. The
+  plaintext exists long enough to go into one email and is never written down.
+- **Minted on the first admin reply, never at submission.** A store with a hundred
+  unanswered enquiries has zero live credentials.
+- Rolling 90-day expiry, extended by each reply; revocable from the CMS.
+
+`/thread/[token]` exchanges the token for an **HttpOnly cookie** and redirects to a
+token-less `/thread`. This is the most important control in the feature: the app sends
+`Referrer-Policy: strict-origin-when-cross-origin`, so a token left in the address bar
+would travel in the `Referer` header of every same-origin navigation, and into history,
+screenshots and proxy logs.
+
+Every failure — expired, revoked, never existed — renders the *same* page. Distinguishing
+them would make the route an oracle.
+
+Reading the thread uses the service role **after** verifying the token in application
+code. No RLS policy here authenticates an anonymous caller by token, and none was
+invented; this matches how `/api/mcp` treats `mcp_access_tokens`.
+
+## Contact forms and `form_key`
+
+A form block used to store its destination in its own `content`. `FormBlockRenderer` is
+a `"use client"` component that receives that content wholesale, so **the address was
+serialized into the RSC payload of every page carrying a form** — published in the
+markup.
+
+Migration `00000000000027` moved every stored address into `form_endpoints` and left a
+`form_key` behind: an opaque handle that grants nothing and is safe to serialize. The
+migration walks three shapes, because a form nested in a section has no `blocks` row of
+its own:
+
+1. `blocks.content` where `block_type='form'`
+2. `blocks.content` where `block_type='section'` (`column_blocks`, `slides`)
+3. `content_drafts.blocks` / `product_drafts.blocks`
+
+`form_endpoints.fields` is a **server-side snapshot** of the field manifest, so
+notification emails and the inbox render labels the browser did not supply.
+
+`BlockRenderer` and `SectionBlockRenderer` also strip `recipient_email` defensively
+before handing content to the client — an import, a restored revision, or a fork that
+has not migrated can still produce one.
+
+## Delivery is best-effort; the row is the record
+
+`sendEmail` **throws** when SMTP is unconfigured, and a store that has not finished one
+piece of setup often has not finished the other. So every path writes first and notifies
+afterwards, inside `after()`. A failed send sets `email_delivered = false` and records
+`email_error`; the CMS shows "Not emailed" rather than pretending the owner was told.
+
+The visitor is still shown success, because from their side it *was* one.
+
+## Recipient resolution
+
+Contact forms: per-form `form_endpoints.recipient_email` → `site_settings.forms_contact`
+→ the seller-contact ladder (`lib/commerce/seller-contact.ts`: explicit store contact →
+invoice email → privacy support email → oldest ADMIN's auth email). The sandbox
+overrides everything.
+
+**The address is never sent to the browser.** The form posts a `form_key`; the server
+resolves the destination.
+
+## The reply link and `NEXT_PUBLIC_URL`
+
+`sendThreadNotice` refuses to send when the site URL was never configured, but happily
+sends a local URL you chose deliberately.
+
+`resolveSiteUrl()` falls back to `http://localhost:3000` when nothing is set, and a link
+to that is dead for anyone not sitting at the machine. What must never happen is the code
+*inventing* a localhost link because nothing was configured and mailing it to a customer.
+A deliberate local URL is different: that is how you test the round trip, and it works.
+
+So: honour an explicit choice, refuse an accidental default.
+
+- Testing locally: set `NEXT_PUBLIC_URL=http://localhost:3000` (or your dev port). The
+  link is sent and works on that machine; a warning is logged saying who can open it.
+- Production: set it to the public site URL. Vercel's project URL is picked up
+  automatically.
+- Unset: the notice is refused and the reason is recorded on the message.
+
+> An earlier version of this document blamed a `localhost` link for a quarantined
+> message. That was wrong — a probe carrying exactly such a link was delivered normally.
+> The real cause is below.
+
+## Mail threading: two conversations, two roots
+
+Outbound mail carries `In-Reply-To` and `References` pointing at a stable synthetic root,
+because a `Re:` subject with no threading headers is itself a forged-reply heuristic, and
+one consistent id per conversation groups the exchange in the recipient's client.
+
+**The owner's notifications and the visitor's notices use DIFFERENT roots**, and that
+separation is load-bearing:
+
+- owner: `<nb-thread-{id}-admin@{from-domain}>`
+- visitor: `<nb-thread-{id}-visitor@{from-domain}>`
+
+They are two different exchanges with two different people. Sharing one root makes a mail
+client fold them into a single conversation — and when an operator tests with their own
+address as both the admin *and* the enquiring visitor (the obvious way to try the
+feature), the reply is delivered, accepted, and then collapsed under the notification
+they already read. It looks precisely like the email never arrived.
+
+That symptom is a same-mailbox testing artifact, not a production fault: in real use the
+customer and the shop owner are different mailboxes. But the shared root was a genuine
+modelling error, and it is fixed.
+
+## Where a form's mail goes
+
+One rule, three rungs:
+
+1. The form's own `form_endpoints.recipient_email`, if someone set one.
+2. The site contact address from **CMS → Messages** (`site_settings.store_contact`).
+3. The **first admin account's** own login address.
+
+**A form has no address of its own by default**, and that is the intended state — since
+the messaging system arrived, an operator does not need to think about per-form routing
+at all. Submissions are stored as threads and answered in the CMS; the notification
+address is one site-wide setting. A per-form address exists only to route one particular
+form elsewhere — a careers form to HR, say.
+
+Because rung 3 always resolves on a provisioned install, a fresh site reaches a real
+human without configuring anything.
+
+The sandbox overrides all of it: `resolveFormRecipient` returns `SANDBOX_CONTACT_EMAIL`
+when `NEXT_PUBLIC_IS_SANDBOX` is set, so the hosted demo routes to the operator's inbox
+without storing an address anywhere.
+
+### Placeholder addresses count as unset
+
+The starter content used to ship a contact form addressed to `contact@example.com`, and
+migration 27 faithfully carried that into `form_endpoints`. Faithful was wrong:
+`example.com` is reserved by RFC 2606 so it can never be registered, which makes the
+address *guaranteed* undeliverable while looking like a real setting to every layer
+downstream. The visitor is thanked, the relay accepts, nobody is notified, nothing errors.
+An install ran that way without knowing.
+
+Migration 29 clears those to NULL, so they fall through to the ladder above.
+`lib/email/placeholder-address.ts` also treats the reserved domains (`example.com/.org/
+.net/.edu` and the `.example`, `.invalid`, `.test`, `.localhost`, `.local` suffixes) as
+unset at runtime, and `lib/cms/contact-reminder.ts` raises an ADMIN banner if one
+reappears — via an import, a restored revision, or someone typing it.
+
+The banner stays quiet when a form simply has no address, because that is now the correct
+configuration rather than an omission.
+
+## Subjects are per-conversation, and why that matters
+
+|  | contact form | product enquiry |
+|---|---|---|
+| **owner** | `Nicolas sent you a message [NRH-VWQOLB]` | `Nicolas asked about Brass Kettle [NRH-EMISCX]` |
+| **visitor** | `New Roots Herbal replied to your message [NRH-VWQOLB]` | `New Roots Herbal replied about Brass Kettle [NRH-EMISCX]` |
+
+`threadReference(threadId, siteName)` folds the first 32 bits of the thread id into six
+base36 characters and prefixes the site's initials — about 2.2 billion references, read as
+a ticket number rather than a hex dump.
+
+**There is no `Re:` anywhere.** The visitor's message was never an email, so a reply
+prefix is both a spam heuristic and a small lie; naming the site is what actually tells
+them who is writing. The `In-Reply-To` / `References` headers still group each
+conversation properly.
+
+The reference is not decoration. **Exchange derives its ConversationTopic from the
+subject, not from References**, so separating the References headers — necessary, and
+done — was not sufficient. With a constant subject, every enquiry a site ever receives
+collapses into one Outlook conversation, and anything applied to that conversation applies
+to all of them: a rule, a filter, or Ignore Conversation.
+
+A real install hit exactly this. Replies were accepted by the relay, accepted by Microsoft
+with `250 Queued mail for delivery`, and routed straight to Deleted Items, because a
+"Contact form" conversation had been ignored at some point. Nothing anywhere reported a
+fault. It was isolated by sending two messages with byte-identical bodies and different
+subjects: the unique subject arrived, `Re: Contact form` did not. When mail "doesn't
+arrive", that A/B is the first thing to run — not a theory.
+
+## Deliverability: accepted is not delivered
+
+A reply can be accepted by the relay, accepted by the recipient's server with
+`250 Queued mail for delivery`, appear in the inbox — and then be **removed from the
+mailbox minutes later**. Microsoft calls this ZAP (Zero-hour Auto Purge): threat intel
+updates after delivery and the message is retracted. There is no bounce and no SMTP
+error, so `email_delivered = true` is accurate and every log upstream reports success.
+
+**This is largely outside the application's control.** A strict corporate tenant can
+purge a transactional message on its overall shape — a reply-styled body carrying a
+quoted excerpt and a link to an opaque tokenised URL — and no rendering tested reliably
+survived one such tenant. An intermediate result suggesting that showing the destination
+URL was the deciding factor did not hold up against the real notice.
+
+What the application does do:
+
+**1. No secrecy language.** The message used to end "This link is personal to you —
+please don't forward it." A secret one-off link, a prominent button, and an instruction
+not to share it is a near-literal phishing template. The link's security comes from the
+token rotating on every reply, not from asking the recipient to keep a secret.
+
+**2. The destination is visible.** The call-to-action is a button, with the URL also
+printed as plain text beneath it. Good practice regardless, and it survives clients that
+strip styling.
+
+**3. There is a manual channel.** `createVisitorLink` mints a link and hands it to the
+admin without sending anything ("Copy visitor link" in the thread pane). When a
+recipient's filtering removes the mail, the conversation is still intact and the link is
+still obtainable — send it by whatever works.
+
+### Diagnosing it
+
+Send messages with **byte-identical bodies** differing in exactly one variable, and check
+the recipient's Deleted Items as well as the inbox. Reasoning from correlation produced
+five wrong answers here — a `localhost` link, spam filtering in general, a shared thread
+root, the subject line, and the secrecy phrase — each of which fitted the evidence and
+was killed by the next test.
+
+The send path logs what actually went out:
+
+```
+[messages] Reply on thread <id> handed to SMTP — to="…" replyTo="…" subject="…" link=tokenised
+```
+
+Start there. **Accepted by SMTP is not arrived, and arrived is not still there.** When a
+tenant is purging on shape, testing against a different provider (a personal Gmail, say)
+separates "the app is broken" from "this mailbox rejects this class of mail".
+
+## Rate limiting
+
+There is no shared rate limiter in this repo. Both public write paths throttle by
+counting recent rows for a masked IP, and both **fail closed**: an absent or unparseable
+`X-Forwarded-For` buckets under the literal `'unknown'` rather than skipping the check.
+Trusted platform headers (`x-vercel-forwarded-for`, `x-real-ip`) are preferred over
+`x-forwarded-for`, whose leftmost entry the client can write.
+
+## Files
+
+- `libs/db/src/supabase/migrations/00000000000027_message_threads.sql` — private lane, `form_endpoints`, the form-block data migration
+- `libs/db/src/supabase/migrations/00000000000028_interaction_replies.sql` — `parent_id`, the reply CHECK, and the indexes `cms_interactions` never had
+- `apps/nextblock/lib/messages/thread-token.ts` (+ `.test.ts`) — mint, parse, verify
+- `apps/nextblock/lib/messages/threads.ts` — thread creation, recipient resolution, both notification emails
+- `apps/nextblock/app/thread/**` — the visitor's page and the token-exchange route
+- `apps/nextblock/app/actions/threadActions.ts` — visitor replies
+- `apps/nextblock/app/cms/messages/**` — the inbox, its loader and its admin actions
+- `apps/nextblock/app/actions/interactions.ts` — `replyToInteraction`, the public lane
+- `apps/nextblock/components/StaffReplies.tsx` — nested public replies on the storefront
+
+`/cms/inquiries` and `/cms/interactions` are now redirects into the inbox; both were
+linked from notification emails and bookmarks, so neither was deleted.
+
+## Known gaps
+
+- Interactions have **no per-user read marker** anywhere in the schema, so the nav badge
+  counts "pending moderation". Two admins working the queue see the same number.
+- Public replies do not email the review/comment author. They have a reachable address,
+  but that would be the first time the platform emails a registered user about content
+  activity, with no preference to opt out of.
+- Visitors get no acknowledgement email at submission time — that would require minting
+  a token immediately, which is exactly the live-credential surface this design avoids.

package/templates/nextblock-template/docs/README.md

@@ -1,41 +1,42 @@
-# NextBlock CMS Documentation
-
-This folder is the source-of-truth reference set for the NextBlock monorepo.
-The numbered files are written from live code, routes, migrations, and shipped
-library surfaces rather than historical planning notes.
-
-## Start Here
-
-- Product and architecture overview: [01-PROJECT-OVERVIEW.md](./01-PROJECT-OVERVIEW.md)
-- Commerce capabilities: [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md)
-- CMS editor and block system: [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md)
-- Database, auth, and migrations: [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
-- Contributor workflow and local operations: [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md)
-- CLI and scaffolded project flow: [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md)
-- Block SDK and extensibility surface: [07-BLOCK-SDK-AND-EXTENSIBILITY.md](./07-BLOCK-SDK-AND-EXTENSIBILITY.md)
-- Cortex AI architecture: [08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md)
-- Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
-- Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
-- Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
-- One-click cloud deploy (Deploy to Vercel): [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md)
-- Updating an install (`npm run update`, upstream sync): [13-STAYING-UP-TO-DATE.md](./13-STAYING-UP-TO-DATE.md)
-
-## Audience Guide
-
-- New contributors: read `01`, then `04`, then `05`.
-- Commerce work: read `02`, then `04`.
-- Editor or page-builder work: read `03`, then `07`.
-- Custom block work: read `03`, then `10`.
-- AI / Cortex work: read `08`.
-- CLI or template work: read `06`.
-- Publishing the libraries / scaffold CLI: read `06`.
-- Running everything locally without cloud accounts: read `11`.
-- One-click cloud deploy and the browser setup wizard: read `12`.
-- Updating an existing install, whichever way it was created: read `13`.
-- AI agents: start with this index, then move directly to the subsystem file that
-  matches the task. Treat `apps/nextblock`, `libs/*`, and
-  `libs/db/src/supabase/migrations` as the final authority if a doc and code ever
-  disagree.
-- AI agents touching migrations must also read the root `AGENTS.md` note:
-  production/shared database changes are append-only and non-destructive by
-  default.
+# NextBlock CMS Documentation
+
+This folder is the source-of-truth reference set for the NextBlock monorepo.
+The numbered files are written from live code, routes, migrations, and shipped
+library surfaces rather than historical planning notes.
+
+## Start Here
+
+- Product and architecture overview: [01-PROJECT-OVERVIEW.md](./01-PROJECT-OVERVIEW.md)
+- Commerce capabilities: [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md)
+- CMS editor and block system: [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md)
+- Database, auth, and migrations: [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
+- Contributor workflow and local operations: [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md)
+- CLI and scaffolded project flow: [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md)
+- Block SDK and extensibility surface: [07-BLOCK-SDK-AND-EXTENSIBILITY.md](./07-BLOCK-SDK-AND-EXTENSIBILITY.md)
+- Cortex AI architecture: [08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md)
+- Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
+- Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
+- Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
+- One-click cloud deploy (Deploy to Vercel): [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md)
+- Updating an install (`npm run update`, upstream sync): [13-STAYING-UP-TO-DATE.md](./13-STAYING-UP-TO-DATE.md)
+- Messages inbox (enquiries, contact forms, reviews, comments): [14-MESSAGES-INBOX.md](./14-MESSAGES-INBOX.md)
+
+## Audience Guide
+
+- New contributors: read `01`, then `04`, then `05`.
+- Commerce work: read `02`, then `04`.
+- Editor or page-builder work: read `03`, then `07`.
+- Custom block work: read `03`, then `10`.
+- AI / Cortex work: read `08`.
+- CLI or template work: read `06`.
+- Publishing the libraries / scaffold CLI: read `06`.
+- Running everything locally without cloud accounts: read `11`.
+- One-click cloud deploy and the browser setup wizard: read `12`.
+- Updating an existing install, whichever way it was created: read `13`.
+- AI agents: start with this index, then move directly to the subsystem file that
+  matches the task. Treat `apps/nextblock`, `libs/*`, and
+  `libs/db/src/supabase/migrations` as the final authority if a doc and code ever
+  disagree.
+- AI agents touching migrations must also read the root `AGENTS.md` note:
+  production/shared database changes are append-only and non-destructive by
+  default.

package/templates/nextblock-template/lib/blocks/blockColors.test.ts

@@ -39,12 +39,26 @@ describe('resolveTextColor', () => {
     expect(resolveTextColor(undefined)).toEqual({});
     expect(resolveTextColor(null)).toEqual({});
     expect(resolveTextColor('')).toEqual({});
-    expect(resolveTextColor('chartreuse')).toEqual({});
+    expect(resolveTextColor('notacolour')).toEqual({});
     expect(resolveTextColor('javascript:alert(1)')).toEqual({});
     expect(resolveTextColor('url(https://evil.test/x.png)')).toEqual({});
+    // A valid name with anything appended is not a name — this is the injection case,
+    // and it must stay rejected even though `red` on its own is now accepted.
     expect(resolveTextColor('red; background: url(x)')).toEqual({});
   });
 
+  it('accepts CSS named colours, which seeded and AI-authored content actually uses', () => {
+    // The seeded contact-page heading is `textColor: "white"`. It matched neither a
+    // token nor the hex/rgb/hsl pattern, so it resolved to {} and the white-on-dark hero
+    // rendered dark-on-dark with nothing reporting a problem.
+    expect(resolveTextColor('white')).toEqual({ style: { color: 'white' } });
+    expect(resolveTextColor('Black')).toEqual({ style: { color: 'Black' } });
+    expect(resolveTextColor('  transparent ')).toEqual({ style: { color: 'transparent' } });
+
+    // Still distinguishable from a theme token, which resolves to a class instead.
+    expect(resolveTextColor('accent')).toEqual({ className: 'text-accent' });
+  });
+
   it('never emits an interpolated class name', () => {
     for (const token of TEXT_COLOR_TOKENS) {
       const { className } = resolveTextColor(token);
@@ -73,7 +87,11 @@ describe('guards', () => {
     expect(isTextColorToken('accent')).toBe(true);
     expect(isTextColorToken('#FFF')).toBe(false);
     expect(isCustomCssColor('#FFF')).toBe(true);
+    expect(isCustomCssColor('white')).toBe(true);
+    // A theme token is not a literal colour: the two share one field and are told apart
+    // only here, so this must keep answering false.
     expect(isCustomCssColor('accent')).toBe(false);
+    expect(isCustomCssColor('notacolour')).toBe(false);
   });
 });
 
@@ -103,7 +121,9 @@ describe('HeadingBlockSchema.textColor', () => {
   });
 
   it('rejects values that are neither a token nor a colour', () => {
-    for (const bad of ['nonsense', 'url(x)', 'red', '']) {
+    // 'red' was in this list only because named colours used to be rejected wholesale.
+    // It is a real colour and is now accepted; the genuinely invalid values stay here.
+    for (const bad of ['nonsense', 'url(x)', 'red; background: url(x)', '']) {
       expect(HeadingBlockSchema.safeParse({ ...base, textColor: bad }).success).toBe(false);
     }
   });

package/templates/nextblock-template/lib/blocks/blockColors.ts

@@ -82,12 +82,55 @@ export const TEXT_COLOR_TOKEN_OPTIONS = TEXT_COLOR_TOKENS.map((token) => ({
 export const CSS_COLOR_PATTERN =
   /^(#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})|rgba?\([^)]+\)|hsla?\([^)]+\))$/i;
 
+/**
+ * CSS named colours, which the picker never emits but hand-authored and AI-authored
+ * content does.
+ *
+ * The seeded contact page sets `textColor: "white"` on its heading. That is perfectly
+ * valid CSS, but it matched neither a theme token nor the literal pattern above, so
+ * `resolveTextColor` returned `{}` and the heading quietly inherited the dark default —
+ * a white-on-dark hero rendering dark-on-dark, with nothing anywhere reporting a problem.
+ *
+ * Spelled out as a set rather than folded into the pattern as `[a-z]+`, because
+ * `isCustomCssColor` has to keep answering false for a theme token like `accent`: the
+ * two are stored in the same field and told apart only by these predicates.
+ */
+const CSS_NAMED_COLORS = new Set(
+  (
+    'aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue ' +
+    'blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk ' +
+    'crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkgrey darkkhaki ' +
+    'darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen ' +
+    'darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue ' +
+    'dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite ' +
+    'gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo ivory khaki ' +
+    'lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan ' +
+    'lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen ' +
+    'lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen ' +
+    'magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen ' +
+    'mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream ' +
+    'mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid ' +
+    'palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum ' +
+    'powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown ' +
+    'seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen ' +
+    'steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow ' +
+    'yellowgreen transparent currentcolor'
+  ).split(' ')
+);
+
+export function isCssNamedColor(value: unknown): value is string {
+  return typeof value === 'string' && CSS_NAMED_COLORS.has(value.trim().toLowerCase());
+}
+
 export function isTextColorToken(value: unknown): value is TextColorToken {
   return typeof value === 'string' && (TEXT_COLOR_TOKENS as readonly string[]).includes(value);
 }
 
 export function isCustomCssColor(value: unknown): value is string {
-  return typeof value === 'string' && CSS_COLOR_PATTERN.test(value.trim());
+  return (
+    (typeof value === 'string' && CSS_COLOR_PATTERN.test(value.trim())) ||
+    isCssNamedColor(value)
+  );
 }
 
 export interface ResolvedTextColor {