@proveanything/smartlinks 2.0.56 → 2.0.58

package/docs/connectors.md

@@ -0,0 +1,241 @@
+# Integration connectors
+
+A **connector** is an app that knows one external provider (a PIM, a content network, a shop
+platform…). It is installed on a collection like any app, versioned and released like any app, and
+it adds a manifest `connector` block plus a handful of [server functions](server-functions.md) the
+integration engine and the integrations console call by convention.
+
+Three layers, each with one job:
+
+| Layer | Holds |
+|---|---|
+| **Engine** (the API) | [Integration flows](integrations.md), runs and their logs, triggers (events, schedule, Run now), the secret store, **the mapping** (each customer's field mappings and rules), generic transports (HTTP, Event Hub). No provider code. |
+| **Integrations console** (a core app) | The one admin screen: installed connectors, connect forms, settings, the mapper with AI assist, flows, runs. |
+| **Connector apps** | One per provider: an **adapter**. Talks to the provider and converts between its format and a clean, provider-neutral document. |
+
+**A connector adapts; core maps.** A connector never holds a customer's mapping. It turns the
+provider's records into provider-neutral documents (`shape`), or provider-ready payloads out of
+documents core has already mapped (`serialize`). Every customer's mapping, routing and rules live in
+core, so they work the same for every provider and can be replayed and traced. This is the line
+SnapLogic (endpoint Snaps vs the Mapper), MuleSoft and Airbyte all draw.
+
+A flow that only posts JSON to a webhook or an Event Hub needs no connector; it uses the engine's
+generic transports (see [integrations.md](integrations.md)).
+
+**No AI at run time.** The AI helps an admin *author* a mapping in the console (from the connector's
+target schema plus real sample records); a person approves it, and it is saved as data and runs
+deterministically. A connector's `shape` and `serialize` must be deterministic too.
+
+---
+
+## The manifest block
+
+```jsonc
+// app.manifest.json
+"connector": {
+  "provider": "oneworldsync",
+  "title": "1WorldSync",
+  "directions": ["inbound"],
+  "entities": ["product"],
+  "connection": {
+    "fields": [
+      // Optional: SmartLinks' own credentials are the default; a customer may enter theirs.
+      { "name": "appId",     "label": "App ID",     "secret": "oneworldsync-app-id" },
+      { "name": "secretKey", "label": "Secret key", "secret": "oneworldsync-secret-key" },
+      { "name": "gln", "label": "GLN", "required": true },
+      { "name": "environment", "label": "Environment", "type": "select",
+        "options": [ { "value": "preprod", "label": "Pre-production" }, { "value": "production", "label": "Production" } ] }
+    ]
+  },
+  "settings": {                       // JSON Schema → a form in the console
+    "type": "object",
+    "properties": { "targetMarket": { "type": "string", "default": "GB" } }
+  },
+  "presets": [
+    { "id": "import-products", "title": "Import products", "direction": "inbound", "entity": "product",
+      "flow": { "config": { "fieldMappings": [ /* a suggested mapping the customer can edit */ ] } } }
+  ],
+  "functions": {                      // names of this app's server functions
+    "testConnection": "testConnection",
+    "describeTarget": "describeTarget",
+    "sample": "sample",
+    "shape": "shape",
+    "fetch": "fetch"
+  },
+  "panels": [ { "id": "explorer", "title": "Explorer", "component": "Explorer" } ],
+  "aiGuide": "connector-ai-guide.md"
+},
+"functions": {
+  "files": { "js": { "umd": "dist/functions.umd.js" } },
+  "definitions": [
+    { "name": "testConnection", "trigger": { "type": "http", "method": "POST" },
+      "visibility": "admin", "authority": "collection",
+      "capabilities": ["network:content1-api.1worldsync.com", "secrets:oneworldsync-app-id", "secrets:oneworldsync-secret-key"] }
+    // …one definition per function named above
+  ]
+}
+```
+
+Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`src/types/appManifest.ts`).
+
+| Field | Meaning |
+|---|---|
+| `provider` | Stable provider key (`syndigo`, `oneworldsync`). |
+| `title` | Provider display name; defaults to the app name. |
+| `directions` | `inbound` (provider → SmartLinks), `outbound` (SmartLinks → provider), or both. |
+| `entities` | SmartLinks entities it maps, e.g. `["product"]`. |
+| `connection.fields[]` | The console's **Connect** form. A field with `secret` is stored as this app's secret of that name on the collection (write-only; never returned to the browser). Other fields are saved in the installation's connection settings. |
+| `settings` | JSON Schema for installation settings; the console renders it as a form. |
+| `presets[]` | Ready-made flows ("Products → provider"). A preset's `flow.config.fieldMappings` is a **suggested** mapping: the connector's knowledge of the provider, which the customer accepts or edits in core. |
+| `functions` | Which of this app's server functions implement each step (below). Fill in only what applies. |
+| `panels[]` | Provider-specific screens the console mounts (an API explorer, a status page). |
+| `aiGuide` | A guide the mapping assistant reads: the provider's quirks, required fields, good defaults. |
+
+---
+
+## The functions
+
+Each step names one of the app's server functions. Declare them as **http POST, `visibility:
+"admin"`, `authority: "collection"`**: the engine calls them with no signed-in user (a product edit, a
+schedule), and the console calls the same functions while an admin configures the flow. The input
+arrives as `event.body`; return the result as JSON. Capabilities still cap what each one can do:
+declare the provider's hosts (`network:<host>`) and the secrets it reads (`secrets:<name>`).
+
+| Step | Called by | Input (`event.body`) | Returns |
+|---|---|---|---|
+| `testConnection` | Connect form, **Test** | `{ installation }` | `ConnectorTestResult` `{ ok, message }` |
+| `describeTarget` | Mapper opens | `{ installation }` | `ConnectorTargetSchema` `{ fields: [{ path, label, type, required, enum }] }`: the provider's fields *for this customer*. Outbound mappings target these paths. |
+| `sample` | Mapper, AI assist, dry run | `{ installation, limit }` | `ConnectorRecords` `{ records }`: real provider records |
+| `fetch` | Every inbound run | `ConnectorFetchInput` `{ installation, cursor, limit }` | `ConnectorRecords` `{ records, nextCursor }`: one page per call |
+| `shape` | Every inbound run (and sample dry runs) | `ConnectorShapeInput` `{ installation, records }` | `ConnectorShapeResult` `{ documents, skipped }`: one provider-neutral document per record, same order; `null` skips one |
+| `serialize` | Every outbound run | `ConnectorSerializeInput` `{ installation, documents, eventType? }`: documents core mapped to `describeTarget` paths; a deletion arrives as `{ id, _deleted: true }` | `ConnectorSerializeResult` `{ payloads, skipped }`: one provider payload per document, same order; `null` skips one |
+| `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId }] }` |
+
+**How a run flows:**
+- **Inbound:** `fetch` (paged) → `shape` → core maps the documents with the flow's mapping → upsert.
+- **Outbound:** gather the SmartLinks records → core maps them to the provider's fields → `serialize`
+  → `send` (or a generic transport).
+
+**What happens when a step is left out:**
+- **No `shape`:** core maps the provider records as they come.
+- **No `serialize`:** the mapped documents are sent as they are.
+- **No `send`:** the flow's own transport is used: HTTP (`config.connection`), or Azure Event Hub with
+  `config.transport: 'eventhub'` and `config.eventHub`.
+- **No `describeTarget`:** the mapper offers free-text target paths.
+
+**What `shape` should produce:** plain, predictable JSON a person can map without reading the
+provider's documentation. Flatten the provider's envelopes, name things plainly, keep codes alongside
+their meanings, and put repeated sections (ingredients, allergens, nutrients, images) in arrays. The
+same provider record always gives the same document.
+
+### `installation`
+
+Every step receives the installation it serves:
+
+```ts
+interface ConnectorInstallation {
+  collectionId: string
+  appId: string             // the connector app
+  flowId?: string | null    // when called for a flow
+  connection: Record<string, unknown>   // non-secret Connect-form fields
+  settings: Record<string, unknown>     // installation settings, with the flow's overrides on top
+}
+```
+
+Secrets are never in it. Read them in the function with `ctx.secrets.get('<name>')`, which needs the
+matching `secrets:<name>` capability. A secret the customer set on their collection wins; otherwise the
+connector's own app-level secret of that name (set in Forge) is used, so a connector can ship with
+SmartLinks' credentials as the default.
+
+### Example: `fetch` and `shape`
+
+```ts
+// src/functions/index.ts (the app's functions bundle)
+import type { ConnectorFetchInput, ConnectorRecords, ConnectorShapeInput, ConnectorShapeResult } from '@proveanything/smartlinks'
+
+export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
+  const { installation, cursor, limit = 50 } = event.body as ConnectorFetchInput
+  const appId = await ctx.secrets.get('provider-app-id')
+  const key = await ctx.secrets.get('provider-secret-key')
+  const res = await ctx.fetch(buildSignedUrl(installation, { cursor, limit }, appId, key))
+  const page = await res.json()
+  return { records: page.items, nextCursor: page.next ?? null }
+}
+
+export async function shape(_ctx: any, event: any): Promise<ConnectorShapeResult> {
+  const { records } = event.body as ConnectorShapeInput
+  return {
+    documents: records.map((r: any) => ({
+      gtin: r.item?.gtin,
+      name: r.item?.tradeItemDescription?.[0]?.value,
+      brand: r.item?.brandName,
+      ingredients: (r.item?.ingredients ?? []).map((i: any) => ({ name: i.name, percent: i.percentage })),
+    })),
+  }
+}
+```
+
+---
+
+## Where configuration lives
+
+| What | Where |
+|---|---|
+| Connect-form values (non-secret), installation settings | The connector app's config on the collection, in its admin-only zone (`admin.connector.connection`, `admin.connector.settings`). |
+| Credentials | The connector app's secrets, by the names its fields declare (the customer's on their collection, else the connector's default). |
+| One flow's use of the connector | The flow: `config.connector = { appId, preset?, settings? }` (per-flow settings override the installation's), plus `config.fieldMappings`, which core runs. |
+
+```ts
+await integrations.createFlow(collectionId, {
+  appId: 'core-integrations',
+  direction: 'inbound',
+  name: 'Import products from 1WorldSync',
+  status: 'active',
+  schedule: '0 * * * *',
+  targetEntity: 'product',
+  config: {
+    connector: { appId: 'oneworldsync', preset: 'import-products' },
+    // Maps the connector's shaped documents (not the raw provider records) onto the product.
+    fieldMappings: [ { targetPath: 'name', sourcePath: 'name', transformType: 'direct' } ],
+  },
+})
+```
+
+---
+
+## From the console
+
+```ts
+import { integrations, secrets } from '@proveanything/smartlinks'
+
+const { connectors } = await integrations.listConnectors(collectionId)
+// → [{ appId, name, version, connector, installation: { connection, settings }, secrets: { 'provider-key': { set, hint } } }]
+
+await secrets.put(collectionId, 'provider-key', value, { appId })              // a secret field
+await integrations.saveConnectorInstallation(collectionId, appId, { connection: { environment: 'production' } })
+const test = await integrations.runConnectorStep(collectionId, appId, 'testConnection')
+const target = await integrations.runConnectorStep(collectionId, appId, 'describeTarget')
+const { records } = await integrations.runConnectorStep(collectionId, appId, 'sample', { limit: 5 })
+const shaped = await integrations.runConnectorStep(collectionId, appId, 'shape', { records })      // dry run
+const wire = await integrations.runConnectorStep(collectionId, appId, 'serialize', { documents })  // dry run
+```
+
+`send` and `fetch` only run inside a flow. A flow run's summary carries `sent` (outbound) or
+`created` / `updated` / `skipped` (inbound), and every run, inbound or outbound, is in the run history.
+
+---
+
+## Panels
+
+A connector can contribute screens to the integrations console (an API explorer, say). Each
+`panels[]` entry names a component exported from the app's widgets bundle; the console mounts it
+host-side and passes it the collection and the installation. Panels are admin-only and call the
+connector's own functions.
+
+---
+
+## Who can build connectors
+
+First-party connectors run in-process, like any app server function. Third-party connectors will run
+in the isolated runner (see [server-functions.md](server-functions.md)) once that opens up; the contract
+does not change.

package/docs/integrations.md

@@ -15,6 +15,10 @@ Flows are triggered three ways, all converging on the same executor:
   automatically when that entity changes.
 - **schedule** — a flow carrying a cron/interval `schedule` is run by the scan job. *(next)*
 
+Provider-specific logic (a provider's payload format, its API, its connect form) lives in a
+**connector app**, not in the engine: see **[Connectors](connectors.md)**. A flow uses one with
+`config.connector = { appId }`.
+
 Credentials are **never** stored on the flow. The connection holds an opaque
 `credentialRef` into the **sealed-secret store** (`secrets` namespace); the value is sealed
 at rest and resolved server-side only, at execution.

package/docs/overview.md

@@ -94,6 +94,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Lots** | `docs/lots.md` | Cross-SKU production "Lot" entity |
 | **Loyalty** | `docs/loyalty.md` | Points, members, earning rules |
 | **Integrations** | `docs/integrations.md` | Inbound/outbound external-system integration flows |
+| **Connectors** | `docs/connectors.md` | Connector apps: the manifest `connector` block + the functions the integration engine calls |
 | **Item Context** | `docs/item-context.md` | The `itemContext` container prop (serial / NFC authenticity context) |
 | **Native Facade** | `docs/native-facade.md` | `host.native` / `SL.native` device-capability facade |
 | **Product Facets** | `docs/PRODUCT_FACETS_SDK.md` | Facet API reference (admin + public endpoints, types) |

package/docs/site-seo.md

@@ -1,68 +1,69 @@
-# Websites: search engines and AI crawlers (SEO + GEO)
-
-For apps served as websites (an app site at `<name>.smartlinks.host` or a custom domain). Hub sites
-get all of this from Hub.
-
-## What the platform does for you
-
-- **`/robots.txt`, `/sitemap.xml`, `/llms.txt`** are generated on the site's own address. Don't ship
-  `robots.txt` or `sitemap.xml`: one build serves many sites, and sitemap URLs must be absolute on
-  the site's host, which the build can't know.
-- **List every page** in `public/sitemap-paths.txt`, one `<path> [Title]` per line, in menu order
-  (`/ Home`, `/menu Menu`, `/book Book a table`). They go into the sitemap and `llms.txt` (titled)
-  on the right host, and Forge's preview uses the same list as its page menu. Keep it in step with
-  the router. Pre-rendered pages (`about/index.html`) are found automatically.
-- **Canonical address.** A site can answer on its automatic address, a chosen name and a custom
-  domain. Every page gets `Link: <https://{canonical}{path}>; rel="canonical"`, so search engines
-  consolidate on one: the custom domain, else the chosen name, else the automatic address. Don't set
-  your own canonical unless a page has a different canonical page.
-- **Previews stay out of search.** A sandbox collection's sites, and any test build (dev, alpha,
-  beta), are served with `X-Robots-Tag: noindex` and a `robots.txt` that disallows everything,
-  whatever the build ships.
-
-## What you do: `SL.seo` and `SL.site`
-
-```ts
-import * as SL from '@proveanything/smartlinks'
-
-// Per route, from its data — on every route change:
-SL.seo.head({
-  title: `${product.name} — ${brand}`,
-  description: product.description,       // ~150 characters, says what the page is
-  image: product.heroImage?.url,           // absolute; used for link previews
-  type: 'product',                         // 'website' | 'article' | 'product'
-})
-
-// Structured data (schema.org JSON-LD). The id names the block, so calling again replaces it:
-SL.seo.jsonLd('page', SL.seo.schema.product(product, { url: location.href, brand }))
-SL.seo.jsonLd('faq', SL.seo.schema.faqPage(faqs.map((f) => ({ question: f.q, answer: f.a }))))
-SL.seo.jsonLd('org', SL.seo.schema.organization(collection))
-
-// When the page's data has rendered:
-SL.site.ready()
-```
-
-| Builder | For |
-|---|---|
-| `schema.product(product, { url, brand, offer, rating })` | product pages (`offer` only when it's really sold) |
-| `schema.faqPage([{ question, answer }])` | FAQs: rich results, and the answer-shaped content AI search cites |
-| `schema.organization(collection)` | the brand behind the site (home page) |
-| `schema.localBusiness(collection, { type, address, telephone, openingHours })` | a business with a place (`type: 'Florist'`, `'Restaurant'`…) |
-| `schema.breadcrumbs([{ name, url }])` | nested pages |
-| `schema.article({ headline, datePublished, … })` | posts, guides, news |
-
-`seo.head` removes tags a previous route set and the next one doesn't. Both are no-ops without a
-`document` (SSR, tests).
-
-`site.ready()` tells the platform's page renderer the page is complete, so it can snapshot the
-content for crawlers that don't run JavaScript. Without it, the renderer waits for the network to go
-quiet.
-
-## Content that gets found
-
-- **Content in the page, not behind interaction.** FAQ answers in `<details>` are fine; answers
-  fetched only when a question is clicked aren't seen.
-- **One `<h1>` per page**, a logical heading order, `alt` text on content images.
-- **Answer-shaped writing.** A short summary near the top, question-style headings where they fit.
-  This is what AI assistants quote.
-- **Real links** (`<a href>`) between pages, never hash routes.
+# Websites: search engines and AI crawlers (SEO + GEO)
+
+For apps served as websites (an app site at `<name>.smartlinks.host` or a custom domain). Hub sites
+get all of this from Hub.
+
+## What the platform does for you
+
+- **Every page is server-rendered.** A website runs on the SmartLinks site runtime (see
+  [websites.md](websites.md)): the first response for any URL is the finished HTML, with its title,
+  description, link-preview image, structured data and real status codes (404s are 404s). Search
+  engines, AI crawlers and link previews read it without running JavaScript.
+- **`/robots.txt`, `/sitemap.xml`, `/llms.txt`** are generated on the site's own address. Don't ship
+  `robots.txt` or `sitemap.xml`: one build serves many sites, and sitemap URLs must be absolute on
+  the site's host, which the build can't know.
+- **List every page** in `public/sitemap-paths.txt`, one `<path> [Title]` per line, in menu order
+  (`/ Home`, `/menu Menu`, `/book Book a table`). They go into the sitemap and `llms.txt` (titled)
+  on the right host, and Forge's preview uses the same list as its page menu. Keep it in step with
+  the router.
+- **Canonical address.** A site can answer on its automatic address, a chosen name and a custom
+  domain. Every page gets `Link: <https://{canonical}{path}>; rel="canonical"`, so search engines
+  consolidate on one: the custom domain, else the chosen name, else the automatic address. Don't set
+  your own canonical unless a page has a different canonical page.
+- **Previews stay out of search.** A sandbox collection's sites, and any test build (dev, alpha,
+  beta), are served with `X-Robots-Tag: noindex` and a `robots.txt` that disallows everything,
+  whatever the build ships.
+
+## What you do: `SL.seo` and `SL.site`
+
+```ts
+import * as SL from '@proveanything/smartlinks'
+
+// Per route, from its data — on every route change:
+SL.seo.head({
+  title: `${product.name} — ${brand}`,
+  description: product.description,       // ~150 characters, says what the page is
+  image: product.heroImage?.url,           // absolute; used for link previews
+  type: 'product',                         // 'website' | 'article' | 'product'
+})
+
+// Structured data (schema.org JSON-LD). The id names the block, so calling again replaces it:
+SL.seo.jsonLd('page', SL.seo.schema.product(product, { url: location.href, brand }))
+SL.seo.jsonLd('faq', SL.seo.schema.faqPage(faqs.map((f) => ({ question: f.q, answer: f.a }))))
+SL.seo.jsonLd('org', SL.seo.schema.organization(collection))
+
+```
+
+| Builder | For |
+|---|---|
+| `schema.product(product, { url, brand, offer, rating })` | product pages (`offer` only when it's really sold) |
+| `schema.faqPage([{ question, answer }])` | FAQs: rich results, and the answer-shaped content AI search cites |
+| `schema.organization(collection)` | the brand behind the site (home page) |
+| `schema.localBusiness(collection, { type, address, telephone, openingHours })` | a business with a place (`type: 'Florist'`, `'Restaurant'`…) |
+| `schema.breadcrumbs([{ name, url }])` | nested pages |
+| `schema.article({ headline, datePublished, … })` | posts, guides, news |
+
+`seo.head` removes tags a previous route set and the next one doesn't. Both are no-ops without a
+`document`. In a server-rendered site, prefer the router's own head support (TanStack Start's route
+`head()`), so the tags are in the server's HTML; use `SL.seo.schema.*` to build the JSON-LD for it.
+
+`SL.site.ready()` is no longer needed: pages arrive finished from the server.
+
+## Content that gets found
+
+- **Content in the page, not behind interaction.** FAQ answers in `<details>` are fine; answers
+  fetched only when a question is clicked aren't seen.
+- **One `<h1>` per page**, a logical heading order, `alt` text on content images.
+- **Answer-shaped writing.** A short summary near the top, question-style headings where they fit.
+  This is what AI assistants quote.
+- **Real links** (`<a href>`) between pages, never hash routes.

package/docs/websites.md

@@ -0,0 +1,91 @@
+# Websites: server-rendered on the SmartLinks site runtime
+
+A website built on SmartLinks is an app whose public side is a **server-rendered site** at its own
+address: an automatic `*.smartlinks.host` name, a chosen name, or the business's own domain. Every
+page arrives as finished HTML, so search engines, AI crawlers and link previews see the real
+content, and visitors see it before any JavaScript runs.
+
+## How a request is served
+
+```
+visitor / crawler / agent
+  └─► SmartLinks site router (edge)
+        ├─ /robots.txt, /sitemap.xml, /llms.txt     made by the platform (site-seo.md)
+        ├─ a file in your build (has an extension)   served from the build, cached at the edge
+        └─ anything else                             your site's server renders it
+              • runs in an isolated worker, close to the SmartLinks API
+              • may call the SmartLinks API and the hosts you declare, nothing else
+              • request header x-sl-site says which site it is (SL.site.fromRequest)
+```
+
+The router also adds the canonical or noindex header, the security headers, and
+`window.__SMARTLINKS_SITE__` to every HTML page (read in the browser with `SL.site.current()` or
+`SL.readContext()`).
+
+## The build
+
+The website template (TanStack Start) produces this; you don't write it by hand.
+
+```
+dist/
+├── index.html? / assets/…       the client build (hashed files: cached for a year)
+├── sitemap-paths.txt            your pages, "<path> [Title]" per line (site-seo.md)
+├── _server/                     the server bundle: one ES module entry + its chunks
+│   └── index.mjs                exports default { fetch(request, env, ctx) }  (WinterTC)
+└── app.manifest.json
+```
+
+Manifest:
+
+```jsonc
+"site": {
+  "server": {
+    "main": "_server/index.mjs",            // the server entry, inside the build
+    "compatibilityFlags": ["nodejs_compat"] // allowed: nodejs_compat, nodejs_compat_v2, nodejs_als
+  },
+  "network": ["api.example-weather.com"]    // other hosts the server may call (optional)
+}
+```
+
+On publish, the server folder becomes the site's server for that channel. Promote copies the same
+bytes. `_server/` is never served to visitors.
+
+## The server's rules
+
+- **Which site:** `const site = SL.site.fromRequest(request)` gives `{ host, collectionId, appId,
+  channel, canonicalHost }`. One build serves every site it's installed on, so always take the
+  collection from here, never from a constant.
+- **Data:** call the SmartLinks API with the SDK as you would in the browser. The server reads what
+  an anonymous visitor could read on that site, and only that collection. It holds no keys and no
+  signed-in user.
+- **Writes** (contact forms, entries, sign-ups) go to your app's **server functions**
+  (server-functions.md), called from the browser as today. Their capabilities, secrets and limits
+  apply.
+- **Other hosts:** only those in `site.network`. Anything else is refused (`403 Blocked`).
+- **Limits per request:** a CPU-time budget and a cap on outgoing calls. A page that needs more is
+  doing work that belongs in a server function or a scheduled job.
+- **No secrets** in the server bundle and no Node built-ins beyond `nodejs_compat`.
+
+## Caching
+
+The router keeps a rendered page at the edge when your response says it may:
+
+| Your response | At the edge |
+|---|---|
+| `Cache-Control: public, s-maxage=300` (the template's default for pages) | kept up to 5 minutes |
+| `private`, `no-store`, `no-cache`, or a `Set-Cookie` | never kept |
+| no `Cache-Control` | never kept |
+
+Cached pages are keyed by the release and the collection's **content generation**: when products,
+public app records, app settings or the collection change, the generation moves and every page of
+the collection's sites re-renders on its next visit (within about 30 seconds). Publishing a release
+does the same. Tracking parameters (`utm_*`, `gclid`, `fbclid`…) don't create separate entries.
+
+Keep pages the same for every visitor. Anything personal (a signed-in owner's products, a basket)
+renders in the browser after load.
+
+## Locally
+
+`npm run dev` runs the site with your dev collection (`.env`: `VITE_SL_COLLECTION_ID`), because
+there's no router to say which site it is: `SL.site.fromRequest()` is null, so fall back to it.
+Forge's preview runs the same server code the site runtime does.