@preprio/toolkit 0.1.0-beta.5 → 0.2.0-beta.2

package/README.md

@@ -292,7 +292,11 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 
 ### API Integration
 
-Use `getPreprHeaders()` to forward Prepr's personalization context to your own CMS or GraphQL fetches. Without these headers Prepr cannot resolve segments or A/B variants for the request.
+Use `getPreprHeaders()` to forward the request's Prepr personalization context to your Prepr GraphQL fetches. Prepr resolves segments and A/B variants from these headers, so a query sent without them always returns the default, unpersonalized content.
+
+The headers are set by the middleware, so they are only present on routes its matcher covers — off-matcher requests yield an empty object.
+
+The signature differs per framework: `getPreprHeaders()` is async and zero-argument on Next.js (it reads `headers()` for you), while the Astro, SvelteKit, and Nuxt builds are synchronous and take the request's `Headers`.
 
 #### With the Fetch API
 
@@ -364,7 +368,15 @@ export default {
 };
 ```
 
-The loader only rewrites URLs on `*.stream.prepr.io` and `*.b-cdn.net`; anything else passes through untouched. Existing crop and quality transforms in the URL survive the resize.
+The API emits each asset's real dimensions, so a Prepr URL renders as-is:
+
+```
+https://393qibegr87z.b-cdn.net/w_800,h_600,fx_75,fy_67/b7ijwafd586-photo.jpg
+```
+
+The loader rewrites `w_` to the width Next asks for and scales `h_` alongside it, holding the emitted ratio — for a cropped asset that ratio is the authored crop box, so the crop survives the resize. Focal points (`fx`/`fy`) are percentages and carry through unchanged, as does any other option in the segment. Quality is not a CDN option and is ignored.
+
+URLs with no transform segment pass through untouched — set `unoptimized` on those `<Image>`s.
 
 See the runnable example at `examples/nextjs` for the full source of truth.
 
@@ -558,11 +570,11 @@ Forward the headers on your GraphQL fetch with `getPreprHeadersFromHeaders(reque
 **Client** — mount the toolbar imperatively:
 
 ```javascript
-import { createPreprToolbar, loadTrackingPixel } from '@preprio/toolkit';
+import { createPreprPreview, loadTrackingPixel } from '@preprio/toolkit';
 
 loadTrackingPixel('YOUR_ACCESS_TOKEN');
 
-const controller = createPreprToolbar({ props: toolbarProps });
+const controller = createPreprPreview({ props: toolbarProps });
 // later: controller.destroy()
 ```
 
@@ -695,12 +707,12 @@ const { requestHeaders, responseCookies } = processPreprRequest(request, { previ
 // responseCookies: CookieSpec[]  — { name, value, maxAge, path }
 ```
 
-#### `createPreprToolbar(options)`
+#### `createPreprPreview(options)`
 
-Mounts the toolbar and returns a controller.
+Starts the preview runtime — optionally mounting the toolbar — and returns a controller.
 
 ```typescript
-const controller = createPreprToolbar({
+const controller = createPreprPreview({
   props: toolbarProps,
   options: { debug: true, locale: 'nl' },
   navigation: {
@@ -715,13 +727,15 @@ controller.destroy();
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `props` | `PreprToolbarProps` | Required. From `getToolbarProps`. |
-| `options` | `PreprToolbarOptions` | `{ debug?, locale? }`. |
+| `props` | `PreprToolbarProps` | From `getToolbarProps`. Optional — a headless preview has no segment list to pass. |
+| `options` | `PreprPreviewOptions` | `{ debug?, locale?, features?, ui?, allowedEditorOrigins? }`. |
 | `navigation` | `PreprNavigationAdapter` | How segment/variant switches navigate. |
 
 The navigation adapter is optional. Omit it and the toolbar uses `window.location.assign` — a full page load. Supply one to integrate with a client-side router; its `reload` member is optional too, and runs after a preview-mode toggle (defaulting to `window.location.reload()`). The Next.js and SvelteKit wrappers wire all of this up for you.
 
-`createPreprToolbar` is a no-op outside a browser (no `window`/`document`) and returns a controller whose `destroy()` does nothing, so it is safe to call during SSR. It also skips mounting when `prepr_hide_bar=true` is present, which is how the Prepr live-preview iframe suppresses the bar.
+`createPreprPreview` is a no-op outside a browser (no `window`/`document`) and returns a controller whose `destroy()` does nothing, so it is safe to call during SSR.
+
+Chrome is skipped — while every side effect stays wired — when any of these hold: `ui: false`, `?prepr_hide_bar=true` (how the Prepr live-preview iframe suppresses the bar), or running inside the editor's iframe. See [Headless preview](#headless-preview-no-toolbar-ui).
 
 #### `loadTrackingPixel(id, config?)`
 
@@ -798,18 +812,89 @@ createPreprMiddleware(request, response, { preview: true });
 | Option | Type | Description |
 | --- | --- | --- |
 | `preview` | `boolean` | Enables preview mode. The only gate — resolve it from your own environment signal. |
+| `features` | `PreprFeatures` | Disable features app-wide. See [Feature flags](#feature-flags). |
 | `version` | `string` | Override the version reported in the `Prepr-Package` header. Mainly for tests. |
 
-### Toolbar Options
+### Preview Options
 
 ```typescript
-createPreprToolbar({ props, options: { debug: true, locale: 'nl' } });
+createPreprPreview({ props, options: { debug: true, locale: 'nl' } });
 ```
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `debug` | `boolean` | `false` | Enable debug logging. |
 | `locale` | `'en' \| 'nl'` | auto-detected | UI language. Falls back to the first supported browser language, then `en`. |
+| `features` | `PreprFeatures` | all enabled | Which features run. See [Feature flags](#feature-flags). |
+| `ui` | `boolean` | `true` | Mount the visible toolbar. See [Headless preview](#headless-preview-no-toolbar-ui). |
+| `allowedEditorOrigins` | `string[]` | `*.prepr.io` | Exact editor origins allowed to drive this preview, for self-hosted editors. Replaces the wildcard. |
+
+`features` and `ui` are independent: `features` decides *what runs*, `ui` decides *whether the toolbar is visible*.
+
+### Headless preview (no toolbar UI)
+
+`ui: false` keeps every non-visual side effect wired — click-to-edit, the editor bridge, scroll restore, cookies and headers — while rendering no chrome of its own. That is how a site gets live editing, or editor scroll restore, alongside its own UI instead of the Prepr bar.
+
+```typescript
+// Live editing, no bar:
+const preview = createPreprPreview({
+  options: { ui: false, features: { editMode: true } },
+});
+
+preview.destroy();
+```
+
+`props` is optional here — a headless preview that only wants click-to-edit or scroll restore has no segment list to pass. For scroll restore and nothing else:
+
+```typescript
+createPreprPreview({
+  options: {
+    ui: false,
+    features: { segments: false, abTesting: false, editMode: false },
+  },
+});
+```
+
+`?prepr_hide_bar=true` and the editor's own iframe both imply `ui: false`. Outside an iframe the bridge is a no-op, so mounting unconditionally is safe. Call `createPreprPreview` **once per page** — two calls start two bridges and announce the preview twice.
+
+### Feature flags
+
+Preview mode is the master switch. Within it, each feature can be turned off with a `features` object. Everything is **on by default** — omit it and nothing changes.
+
+```typescript
+import type { PreprFeatures } from '@preprio/toolkit';
+
+export const preprFeatures: PreprFeatures = {
+  segments: false,               // or { enabled: false }
+  abTesting: true,
+  editMode: { enabled: false },
+};
+```
+
+| Feature | Off means |
+| --- | --- |
+| `segments` | No segment picker. No `Prepr-Segments` header, from cookie **or** `?prepr_preview_segment`. No segment cookie written. The `_Segments` API call is skipped, saving a round-trip per page. |
+| `abTesting` | No A/B control or variant badge. No `Prepr-ABtesting` header, from cookie **or** `?prepr_preview_ab`. No variant cookie written. |
+| `editMode` | No Edit mode control, no click-to-edit overlay, no close-edit pill. |
+
+Pass the **same object to both sides**. Each enforces its own half, so a feature disabled in only one place is still half-on — the UI would hide a control the middleware still honours:
+
+```typescript
+// server
+createPreprMiddleware(request, { preview: true, features: preprFeatures });
+const props = await getToolbarProps(graphqlUrl, preprFeatures);
+
+// client
+<PreprToolbar {...props} options={{ features: preprFeatures }} />
+```
+
+Every framework's `getToolbarProps` takes `features` as its last argument, and every `<PreprToolbar>` accepts an `options` prop. Keeping the object in one module both sides import is the simplest way to stay in sync.
+
+Disabling a feature also stops its `segment_changed` / `variant_changed` events, and the Reset button ignores it — state the user cannot see is never rewritten.
+
+**`editMode` does not disable the Prepr visual editor.** It governs your site's own click-to-edit affordance. When the Prepr editor frames your site it drives edit mode over its own `postMessage` handshake, which keeps working regardless — that is the CMS operating inside its own iframe, not an affordance offered to your visitors. Treat `editMode: false` as a UI choice, never as a security control.
+
+Feature flags govern the toolbar and the middleware. The toolbar-free scroll-sync entry point carries no personalization state, so there is nothing there to disable.
 
 ### Pixel Options
 
@@ -852,7 +937,7 @@ Because the toolbar renders inside a shadow root, none of your own page CSS —
 The toolbar UI ships with English and Dutch. Pass `locale` explicitly, or omit it to auto-detect from the browser and fall back to `en`:
 
 ```typescript
-createPreprToolbar({ props, options: { locale: 'nl' } });
+createPreprPreview({ props, options: { locale: 'nl' } });
 ```
 
 ## Troubleshooting
@@ -904,7 +989,7 @@ Codes: `INVALID_TOKEN`, `MISSING_TOKEN`, `HTTP_ERROR`, `FETCH_ERROR`, `INVALID_R
 ### Debug Mode
 
 ```typescript
-createPreprToolbar({ props, options: { debug: true } });
+createPreprPreview({ props, options: { debug: true } });
 ```
 
 ## How It Works

package/dist/astro/index.cjs

@@ -30,7 +30,25 @@ __export(astro_exports, {
 module.exports = __toCommonJS(astro_exports);
 
 // src/version.ts
-var VERSION = "0.1.0-beta.5";
+var VERSION = "0.2.0-beta.2";
+
+// src/core/features.ts
+function isEnabled(config) {
+  if (typeof config === "boolean") return config;
+  return config?.enabled ?? true;
+}
+function resolveFeatures(features) {
+  return {
+    segments: isEnabled(features?.segments),
+    abTesting: isEnabled(features?.abTesting),
+    editMode: isEnabled(features?.editMode)
+  };
+}
+var ALL_FEATURES_ENABLED = Object.freeze({
+  segments: true,
+  abTesting: true,
+  editMode: true
+});
 
 // src/core/server.ts
 var PreprError = class extends Error {
@@ -138,16 +156,19 @@ async function getPreprEnvironmentSegments(token) {
     );
   }
 }
-async function getToolbarPropsFromHeaders(headers, token) {
+async function getToolbarPropsFromHeaders(headers, token, features) {
+  const resolved = resolveFeatures(features);
   let segments = [];
-  try {
-    segments = await getPreprEnvironmentSegments(token);
-  } catch {
-    segments = [];
+  if (resolved.segments) {
+    try {
+      segments = await getPreprEnvironmentSegments(token);
+    } catch {
+      segments = [];
+    }
   }
   return {
-    activeSegment: getActiveSegmentFromHeaders(headers),
-    activeVariant: getActiveVariantFromHeaders(headers),
+    activeSegment: resolved.segments ? getActiveSegmentFromHeaders(headers) : null,
+    activeVariant: resolved.abTesting ? getActiveVariantFromHeaders(headers) : null,
     segments,
     data: segments
   };
@@ -247,7 +268,8 @@ function processPreprRequest(request, opts) {
   if (!opts?.preview) {
     return { requestHeaders, responseCookies };
   }
-  const hasPreviewParams = searchParams.has(PARAM_SEGMENT) || searchParams.has(PARAM_VARIANT);
+  const features = resolveFeatures(opts?.features);
+  const hasPreviewParams = features.segments && searchParams.has(PARAM_SEGMENT) || features.abTesting && searchParams.has(PARAM_VARIANT);
   if (!hasPreviewParams) {
     const previewModeCookie = requestCookies.get(COOKIE_PREVIEW_MODE);
     const previewModeEnabled = previewModeCookie !== "false";
@@ -267,16 +289,16 @@ function processPreprRequest(request, opts) {
     });
   }
   if (!isLivePreview) {
-    const segmentCookie = requestCookies.get(COOKIE_SEGMENT);
+    const segmentCookie = features.segments ? requestCookies.get(COOKIE_SEGMENT) : void 0;
     if (segmentCookie) {
       requestHeaders.set("Prepr-Segments", segmentCookie);
     }
-    const abCookie = requestCookies.get(COOKIE_VARIANT);
+    const abCookie = features.abTesting ? requestCookies.get(COOKIE_VARIANT) : void 0;
     if (abCookie) {
       requestHeaders.set("Prepr-ABtesting", abCookie);
     }
   }
-  const previewAb = searchParams.get(PARAM_VARIANT);
+  const previewAb = features.abTesting ? searchParams.get(PARAM_VARIANT) : null;
   if (previewAb !== null) {
     requestHeaders.set("Prepr-ABtesting", previewAb);
     if (!isLivePreview) {
@@ -289,7 +311,7 @@ function processPreprRequest(request, opts) {
       });
     }
   }
-  const previewSegment = searchParams.get(PARAM_SEGMENT);
+  const previewSegment = features.segments ? searchParams.get(PARAM_SEGMENT) : null;
   if (previewSegment !== null) {
     requestHeaders.set("Prepr-Segments", previewSegment);
     if (!isLivePreview) {
@@ -329,8 +351,8 @@ function getActiveVariant(headers) {
 function getPreprHeaders(headers) {
   return getPreprHeadersFromHeaders(headers);
 }
-async function getToolbarProps(headers, token) {
-  return getToolbarPropsFromHeaders(headers, token);
+async function getToolbarProps(headers, token, features) {
+  return getToolbarPropsFromHeaders(headers, token, features);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/astro/index.d.cts

@@ -1,14 +1,31 @@
-interface PreprMiddlewareOptions {
-    /** Enable preview-mode headers (segment/AB overrides, preview bar). */
-    preview?: boolean;
-    /** Override the version reported in Prepr-Package (mainly for tests). */
-    version?: string;
-}
-
 interface PreprSegment {
     readonly _id: string;
     readonly name: string;
 }
+/**
+ * Per-feature config. `false` is shorthand for `{ enabled: false }`; the object
+ * form leaves room for per-feature options later without a breaking change.
+ */
+type PreprFeatureConfig = boolean | {
+    enabled?: boolean;
+};
+/** Toolkit features a consumer can turn off. Omitted keys stay enabled. */
+interface PreprFeatures {
+    /** Segment picker, `Prepr-Segments` header and its cookie/query param. */
+    segments?: PreprFeatureConfig;
+    /** A/B variant switch, `Prepr-ABtesting` header and its cookie/query param. */
+    abTesting?: PreprFeatureConfig;
+    /**
+     * The site's own click-to-edit: the toolbar's Edit mode control, the stega
+     * tooltip/overlay and the close-edit pill.
+     *
+     * NOT a security control, and NOT the Prepr editor's live preview. When the
+     * site is framed by the editor, `prepr:initVE` still activates edit mode —
+     * that is the CMS operating inside its own iframe, not an affordance offered
+     * to visitors. See iframe-bridge.ts.
+     */
+    editMode?: PreprFeatureConfig;
+}
 interface PreprToolbarProps {
     readonly activeSegment: string | null;
     readonly activeVariant: string | null;
@@ -35,6 +52,19 @@ interface PreprHeaders {
     readonly 'Prepr-User-Agent'?: string;
 }
 
+interface PreprMiddlewareOptions {
+    /** Enable preview-mode headers (segment/AB overrides, preview bar). */
+    preview?: boolean;
+    /**
+     * Disable features app-wide. Pass the same object you give the toolbar: a
+     * disabled feature injects no header and persists no cookie, whatever the
+     * request carries.
+     */
+    features?: PreprFeatures;
+    /** Override the version reported in Prepr-Package (mainly for tests). */
+    version?: string;
+}
+
 /**
  * Structural stand-in for Astro's `APIContext`, so this package needs no
  * build-time dependency on `astro`. Only the fields `onPreprRequest` uses.
@@ -71,6 +101,6 @@ declare function getPreprHeaders(headers: Headers): PreprHeaders;
  * your deployment already does — the toolkit reads no environment variables of
  * its own.
  */
-declare function getToolbarProps(headers: Headers, token: string): Promise<PreprToolbarProps>;
+declare function getToolbarProps(headers: Headers, token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
 
 export { type AstroLikeContext, type AstroNext, type PreprMiddlewareOptions, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, onPreprRequest };

package/dist/astro/index.d.ts

@@ -1,14 +1,31 @@
-interface PreprMiddlewareOptions {
-    /** Enable preview-mode headers (segment/AB overrides, preview bar). */
-    preview?: boolean;
-    /** Override the version reported in Prepr-Package (mainly for tests). */
-    version?: string;
-}
-
 interface PreprSegment {
     readonly _id: string;
     readonly name: string;
 }
+/**
+ * Per-feature config. `false` is shorthand for `{ enabled: false }`; the object
+ * form leaves room for per-feature options later without a breaking change.
+ */
+type PreprFeatureConfig = boolean | {
+    enabled?: boolean;
+};
+/** Toolkit features a consumer can turn off. Omitted keys stay enabled. */
+interface PreprFeatures {
+    /** Segment picker, `Prepr-Segments` header and its cookie/query param. */
+    segments?: PreprFeatureConfig;
+    /** A/B variant switch, `Prepr-ABtesting` header and its cookie/query param. */
+    abTesting?: PreprFeatureConfig;
+    /**
+     * The site's own click-to-edit: the toolbar's Edit mode control, the stega
+     * tooltip/overlay and the close-edit pill.
+     *
+     * NOT a security control, and NOT the Prepr editor's live preview. When the
+     * site is framed by the editor, `prepr:initVE` still activates edit mode —
+     * that is the CMS operating inside its own iframe, not an affordance offered
+     * to visitors. See iframe-bridge.ts.
+     */
+    editMode?: PreprFeatureConfig;
+}
 interface PreprToolbarProps {
     readonly activeSegment: string | null;
     readonly activeVariant: string | null;
@@ -35,6 +52,19 @@ interface PreprHeaders {
     readonly 'Prepr-User-Agent'?: string;
 }
 
+interface PreprMiddlewareOptions {
+    /** Enable preview-mode headers (segment/AB overrides, preview bar). */
+    preview?: boolean;
+    /**
+     * Disable features app-wide. Pass the same object you give the toolbar: a
+     * disabled feature injects no header and persists no cookie, whatever the
+     * request carries.
+     */
+    features?: PreprFeatures;
+    /** Override the version reported in Prepr-Package (mainly for tests). */
+    version?: string;
+}
+
 /**
  * Structural stand-in for Astro's `APIContext`, so this package needs no
  * build-time dependency on `astro`. Only the fields `onPreprRequest` uses.
@@ -71,6 +101,6 @@ declare function getPreprHeaders(headers: Headers): PreprHeaders;
  * your deployment already does — the toolkit reads no environment variables of
  * its own.
  */
-declare function getToolbarProps(headers: Headers, token: string): Promise<PreprToolbarProps>;
+declare function getToolbarProps(headers: Headers, token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
 
 export { type AstroLikeContext, type AstroNext, type PreprMiddlewareOptions, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, onPreprRequest };

package/dist/astro/index.js

@@ -1,5 +1,23 @@
 // src/version.ts
-var VERSION = "0.1.0-beta.5";
+var VERSION = "0.2.0-beta.2";
+
+// src/core/features.ts
+function isEnabled(config) {
+  if (typeof config === "boolean") return config;
+  return config?.enabled ?? true;
+}
+function resolveFeatures(features) {
+  return {
+    segments: isEnabled(features?.segments),
+    abTesting: isEnabled(features?.abTesting),
+    editMode: isEnabled(features?.editMode)
+  };
+}
+var ALL_FEATURES_ENABLED = Object.freeze({
+  segments: true,
+  abTesting: true,
+  editMode: true
+});
 
 // src/core/server.ts
 var PreprError = class extends Error {
@@ -107,16 +125,19 @@ async function getPreprEnvironmentSegments(token) {
     );
   }
 }
-async function getToolbarPropsFromHeaders(headers, token) {
+async function getToolbarPropsFromHeaders(headers, token, features) {
+  const resolved = resolveFeatures(features);
   let segments = [];
-  try {
-    segments = await getPreprEnvironmentSegments(token);
-  } catch {
-    segments = [];
+  if (resolved.segments) {
+    try {
+      segments = await getPreprEnvironmentSegments(token);
+    } catch {
+      segments = [];
+    }
   }
   return {
-    activeSegment: getActiveSegmentFromHeaders(headers),
-    activeVariant: getActiveVariantFromHeaders(headers),
+    activeSegment: resolved.segments ? getActiveSegmentFromHeaders(headers) : null,
+    activeVariant: resolved.abTesting ? getActiveVariantFromHeaders(headers) : null,
     segments,
     data: segments
   };
@@ -216,7 +237,8 @@ function processPreprRequest(request, opts) {
   if (!opts?.preview) {
     return { requestHeaders, responseCookies };
   }
-  const hasPreviewParams = searchParams.has(PARAM_SEGMENT) || searchParams.has(PARAM_VARIANT);
+  const features = resolveFeatures(opts?.features);
+  const hasPreviewParams = features.segments && searchParams.has(PARAM_SEGMENT) || features.abTesting && searchParams.has(PARAM_VARIANT);
   if (!hasPreviewParams) {
     const previewModeCookie = requestCookies.get(COOKIE_PREVIEW_MODE);
     const previewModeEnabled = previewModeCookie !== "false";
@@ -236,16 +258,16 @@ function processPreprRequest(request, opts) {
     });
   }
   if (!isLivePreview) {
-    const segmentCookie = requestCookies.get(COOKIE_SEGMENT);
+    const segmentCookie = features.segments ? requestCookies.get(COOKIE_SEGMENT) : void 0;
     if (segmentCookie) {
       requestHeaders.set("Prepr-Segments", segmentCookie);
     }
-    const abCookie = requestCookies.get(COOKIE_VARIANT);
+    const abCookie = features.abTesting ? requestCookies.get(COOKIE_VARIANT) : void 0;
     if (abCookie) {
       requestHeaders.set("Prepr-ABtesting", abCookie);
     }
   }
-  const previewAb = searchParams.get(PARAM_VARIANT);
+  const previewAb = features.abTesting ? searchParams.get(PARAM_VARIANT) : null;
   if (previewAb !== null) {
     requestHeaders.set("Prepr-ABtesting", previewAb);
     if (!isLivePreview) {
@@ -258,7 +280,7 @@ function processPreprRequest(request, opts) {
       });
     }
   }
-  const previewSegment = searchParams.get(PARAM_SEGMENT);
+  const previewSegment = features.segments ? searchParams.get(PARAM_SEGMENT) : null;
   if (previewSegment !== null) {
     requestHeaders.set("Prepr-Segments", previewSegment);
     if (!isLivePreview) {
@@ -298,8 +320,8 @@ function getActiveVariant(headers) {
 function getPreprHeaders(headers) {
   return getPreprHeadersFromHeaders(headers);
 }
-async function getToolbarProps(headers, token) {
-  return getToolbarPropsFromHeaders(headers, token);
+async function getToolbarProps(headers, token, features) {
+  return getToolbarPropsFromHeaders(headers, token, features);
 }
 export {
   getActiveSegment,