# Funnel SEO

The funnel editor includes **SEO → Search, Sharing, Checks** for each step.
These settings are saved with the draft and go public only when an administrator
publishes that revision. Existing documents remain compatible.

## Editor controls

- Search title, description, page topic, language, indexing policy, and optional
  HTTPS canonical override. The search preview is illustrative; search engines
  choose their own result appearance. Page topic is an editing aid and is removed
  from anonymous public page data.
- Independent social title, description, image, and accessible image description.
  Leaving the image blank generates a branded 1200 × 630 PNG from the published
  page at `/f/ID/og/SLUG?v=REVISION`. Custom images use the supplied HTTPS URL.
- Heading controls (automatic or H1–H4), image alt text, and known image dimensions.
  Automatic headings give existing templates a main H1 and subsequent H2s.
- Actionable checks for titles, descriptions, heading structure, image descriptions,
  reserved image space, canonical URLs, social previews, and natural topic usage.
  Character lengths are editing guides, not ranking rules. There is no invented
  SEO score or keyword-density target.
- Optional public business details appear in the footer and Organization JSON-LD.
  WebPage JSON-LD uses the actual title, description, canonical, and language.
  Structured data can be disabled per step. The builder does not invent reviews,
  ratings, business facts, or FAQ rich-result eligibility.

AI generation instructions now request useful page metadata, slugs, semantic
headings, original copy, and natural topic phrasing while preserving existing SEO
settings. AI output remains schema-validated and editable; provider calls were
mock-tested, not live-certified.

## Public pages and discovery

Public HTML contains the page copy, headings, metadata, and escaped JSON-LD before
client JavaScript runs. `/f/ID` permanently redirects to the first step's canonical
path, preserving query parameters used for ad attribution. Canonicals exclude
tracking parameters. Explicit canonical overrides must be complete HTTPS URLs
without queries or fragments; a page canonicalized elsewhere is omitted from its
own sitemap. Unknown or unpublished pages return 404.

Automatic indexing permits landing steps and excludes offer, booking, and
thank-you steps. Operators can explicitly include or exclude a step. Excluded
steps emit `noindex, follow` and stay out of sitemaps; they remain usable in the
funnel. Noindex is not access control.

`/sitemap.xml` lists per-funnel sitemaps at `/f/ID/sitemap.xml`. Publication updates
the lightweight discovery index atomically, unpublishing removes membership, and
draft edits cannot change public discovery or metadata. Sitemap lastmod reflects
publication. Queries expose only published IDs/URLs and timestamps, not workspace
data or leads. The root index reads bounded batches and fails explicitly above
50,000 funnels; additional index partitioning is needed beyond that limit.

Configure **NEXT_PUBLIC_SITE_URL** with the deployment's real public HTTPS origin,
without a path, query, or fragment. Configure it before building and serving the
production frontend. HTTP, localhost, IP, and Tailscale origins are not accepted
for discovery. The origin comes from configuration, never an incoming Host header.
Local development emits noindex headers and `Disallow: /`; production without a
valid public origin keeps funnel metadata noindex and discovery disabled.
Workspace, demo, recovery, and API paths have explicit noindex headers. Private
Tailscale preview stays outside search.

Deploy the additive Hyperchat Convex functions/schema before the updated frontend.
Funnels published before this index exists need to be republished to enter it.
Do not use DevLaunch's separate backend. This increment has not been deployed.

## Performance and verification

Public funnel routes load the shared renderer CSS without workspace/editor CSS.
The public runtime does not import the template catalog. Fonts are self-hosted;
images reserve space when supplied dimensions are available, and later images
are lazy-loaded. These changes support performance but do not certify field Core
Web Vitals. Arbitrary third-party image/video size still affects page speed.

Run the standard type, unit, backend, and production-build checks, then:

```sh
node --import tsx tests/integration/funnel-seo.mjs
```

The integration check starts an isolated production Next server and synthetic
local Convex HTTP fixtures. It checks actual HTML, redirects, canonicals, metadata,
JSON-LD, H1s, visible business details, CSS isolation, robots, both sitemap routes,
PNG sharing images, 404s, and private-preview headers. It makes no cloud calls.
Backend tests verify discovery permissions/boundaries, immutable published SEO,
and unpublish/republish behavior. Browser review covers desktop/390px SEO controls,
sharing and search previews, checks, and saved-draft persistence.

No live Search Console indexing, ranking improvements, field Core Web Vitals,
custom domains, or production crawler acceptance is claimed. After an authorized
public deployment, verify its origin and actual published URLs, submit its sitemap
in the owner's Search Console property, and measure real traffic/page performance.

## Research references

Implementation decisions follow Google's official guidance on
[canonical URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls),
[JavaScript SEO](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics),
[sitemaps](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap),
and [Core Web Vitals](https://developers.google.com/search/docs/appearance/core-web-vitals).