siteplane 0.1.68 → 0.2.0-next.1

package/README.md

@@ -1,9 +1,60 @@
 # siteplane
 
-Siteplane for Next.js websites: `withSiteplane` for `next.config` and the `siteplane` command for Booking.
+Siteplane for Next.js websites (App Router, Next 15 and 16): content you can edit in Siteplane with the current
+content as fallback in your code, a Draft Mode preview for the editor, Booking and the `siteplane` CLI.
 
-The website connection for content editing returns with the new agent connection (`npx siteplane@latest init`).
-Until then this package serves Booking.
+## Connect a website
+
+Run this in the website's folder, or tell your coding agent "Install Siteplane":
+
+```bash
+npx siteplane@next init
+```
+
+Version 0.2 is on the `next` tag until it becomes `latest`.
+
+`init` opens the approval page in the browser. There you sign up or sign in, create the website in Siteplane or pick
+an existing one, and click Connect. If you created the website in Siteplane first, its prompt names the site:
+`npx siteplane@<version> init --site <site ID>`.
+
+`init` then writes `siteplane.config.json`, installs this package, wraps `next.config` in `withSiteplane`, adds the
+route `app/api/siteplane/[...siteplane]/route.ts` and `<SiteplaneBridge />`, and prints the task for the agent.
+Siteplane needs no environment variables or secrets in your project.
+
+## Field API
+
+```tsx
+import { siteplane } from "siteplane";
+
+const title = await siteplane.text("home.hero.title", "Fresh rolls since 1920");
+
+<h1 {...siteplane.attrs("home.hero.title")}>{title}</h1>;
+```
+
+Types: `text`, `longText`, `link` (`{ href, label }`) and `image` (`{ src, alt }`). Values load once per request and
+are cached for 60 seconds; without Siteplane the fallbacks render.
+
+## Commands
+
+```bash
+npx siteplane task                    # the task for the agent
+npx siteplane check                   # checks the fields in the code
+npx siteplane sync                    # checks and reports the fields to Siteplane
+npx siteplane status --url <address>  # checks a deployed address
+```
+
+Optional display names for new fields go into `siteplane.labels.json` (`{ "home.hero.title": "Hero headline" }`).
+
+A website with `basePath` in `next.config` needs no extra setup. Check it with the base path in the address
+(`npx siteplane status --url https://www.example.com/docs`); Siteplane saves that address as the website URL and
+reaches the website below it.
+
+## Analytics
+
+With Analytics on for the site, `init` also adds `<SiteplaneAnalytics siteId="…" />` to the root layout. It counts
+page views, App Router navigations and clicks on elements with `data-siteplane-event="<name>"`, on links to other
+websites, phone numbers and email addresses. It sets no cookies and uses no browser storage; Siteplane counts visitors
+per day on its server. Development builds and the editor's preview send nothing.
 
 ## Booking
 
@@ -13,10 +64,7 @@ export default withSiteplane(nextConfig, { booking: { site: "<immutable-site-id>
 ```
 
 The wrapper adds `/booking/:path*` as a `beforeFiles` rewrite to Siteplane and preserves existing rewrite sections.
-Booking never runs the Editor scanner or headers, even when `siteplane.config.json` exists. Use
-`<a href="/booking">` instead of `next/link`; exclude this path from customer middleware. Configure the public booking
-address in Siteplane and permit Siteplane/Stripe assets and connections in the customer CSP. `siteplane booking check`
-verifies the Site ID in `next.config.*`. The public API uses Site ID plus allowed Origin; no raw Booking key is needed.
+Use `<a href="/booking">` instead of `next/link`; exclude this path from customer middleware.
 
 ```bash
 npx siteplane booking init
@@ -25,18 +73,7 @@ npx siteplane booking sync
 npx siteplane booking test
 ```
 
-`siteplane booking sync` and `siteplane booking test` read the Site ID from `siteplane.booking.json`. The first run
-prints a link and a code and opens the Siteplane approval page, like `gh auth login`; an owner or admin of the website
-checks the code and clicks **Connect**. The agent connection is stored in the user config directory
-(`$SITEPLANE_CONFIG_DIR`, `$XDG_CONFIG_HOME/siteplane`, `%APPDATA%\siteplane` or `~/.config/siteplane`), never in the
-project. Agents without a browser pass the link and code to the user; `--no-browser` skips opening it. A revoked or
-expired connection leads through one new approval.
-
-## Image policy
-
-When the scan includes image fields, `withSiteplane` prepares Next Image and existing Next-config CSP headers for
-Siteplane's image route and your website's `/siteplane-assets/` path. Existing image sources stay in place. Builds
-that serve Siteplane images from the website set `SITEPLANE_SITE_ORIGIN` to the exact public HTTPS website origin;
-local fallback-image builds can omit it. The wrapper adds only those exact patterns: existing sources, custom loaders
-and redirect settings remain unchanged. Keep existing policies and verify Siteplane images through the website's
-actual renderer. This preparation does not authorize hosting.
+`booking sync` and `booking test` read the Site ID from `siteplane.booking.json` and connect through the same browser
+approval. The agent connection is stored in the user config directory (`$SITEPLANE_CONFIG_DIR`,
+`$XDG_CONFIG_HOME/siteplane`, `%APPDATA%\siteplane` or `~/.config/siteplane`), never in the project; `--no-browser`
+skips opening the browser.