@storystick/next 0.0.0-stage → 0.2.0-rc.1

package/LICENSE

@@ -0,0 +1,112 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Tanguy Freycon
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This Agreement shall be governed by the laws of France.

package/PUBLIC-API.md

@@ -0,0 +1,31 @@
+# @storystick/next API contract
+
+Install this candidate explicitly with `@storystick/next@0.2.0-rc.1` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+
+Version 0.2.0-rc.1, cohort `sdk-0.2.0-rc.1`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
+
+This package is a product integration facade. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
+
+| Entry | Status |
+| --- | --- |
+| `.` | Supported beta entry |
+| `./preview-text` | Supported beta entry |
+| `./image` | Supported beta entry |
+| `./file` | Supported beta entry |
+| `./video` | Supported beta entry |
+| `./link` | Supported beta entry |
+| `./query` | Supported beta entry |
+| `./rich-text` | Supported beta entry |
+| `./slice-zone` | Supported beta entry |
+| `./revalidate` | Supported beta entry |
+| `./preview-nav` | Reserved SDK contract |
+| `./preview-nav-location` | Reserved SDK contract |
+| `./preview` | Supported beta entry |
+| `./testing` | Reserved SDK contract |
+| `./server` | Supported beta entry |
+
+The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
+
+Use a generated Query V2 definition. A missing document/singleton returns null, an empty collection returns an empty array, and fetch throws on blocked/degraded execution. Execute exposes the complete result envelope. RSC metadata must remain plain JSON data; request authority must not be stored in shared module state.
+
+The repository is private. Public package availability does not make the monorepo public, and npm provenance from that repository is unavailable. Product and pilot support: [Storystick](https://storystick.app).

package/README.md

@@ -1,3 +1,523 @@
-# Temporary Holding Version
+# @storystick/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Minimal content reads and Preview for the Next.js 15 App Router, with React 19.
+
+```bash
+pnpm add @storystick/next@beta
+```
+
+## Configure once
+
+```ts
+// lib/site.ts
+import { createSite } from '@storystick/next/server'
+import * as definition from '@/generated/storystick/query'
+
+export const site = createSite({
+  definition,
+})
+```
+
+Generate the definition with the Storystick CLI. Credentials come from the
+project connection environment variables. Routable Story types are inferred
+from the generated definition, the site URL comes from
+`STORYSTICK_SITE_URL`, and the project primary locale is available through
+`await site.locale()`. Override these only when an application deliberately
+uses a different policy. The site object contains immutable configuration; it
+never stores a current user's session.
+
+## Read where you render
+
+```tsx
+import { previewTextProps } from '@storystick/next'
+import { site } from '@/lib/site'
+
+export async function Header() {
+  const client = await site.client()
+  const settings = await client.query('siteSettings').selectAll().fetch()
+  return settings && <header {...previewTextProps(settings.fields.siteName)} />
+}
+```
+
+This example assumes a `siteSettings` singleton with a `siteName` field. Keep
+this component in a native layout, page, group or slot. It does not depend on
+a CMS page initializing context. Put `<Storystick />` from `@storystick/next`
+once in a shared layout. Export `GET` and `POST` from `site.handlers` in
+`app/api/storystick/[...action]/route.ts`.
+
+In detached Preview, the SDK owns the editing panel outside the site's layout
+tree. Replacing a layout in the same client navigation preserves the panel and
+its editing connection. Removing `<Storystick />` entirely, leaving Preview, or
+changing project/view ends that lifetime. A full page reload creates a new
+connection; an editor-initiated navigation can restore the panel at its confirmed
+destination. Editor navigation waits for saving and context acceptance, while
+page overlays wait for the corresponding site render. No additional provider or
+SDK option is needed.
+
+For a controlled schema migration, give each candidate deployment a distinct
+`STORYSTICK_APP_BUILD_ID=app:<build-id>` and set
+`STORYSTICK_APP_BUILD_DIGEST` to the build artifact's lowercase SHA-256. The
+opt-in `/api/storystick/migration-readback` endpoint then reports this build's
+project, generated query-schema fingerprint and the schema version actually
+read through its server SDK. The ordinary health route stays lightweight.
+These values are deployment claims plus an observed endpoint read, not a
+cryptographic attestation of every running instance or a replacement for
+checking B in Studio Preview before authority transfer.
+
+Queries use Query V2 directly: `select`, `where`, `orderBy`, `page` and `by`.
+`.fetch()` returns exact data and throws `QueryExecutionError` for blocked or
+degraded execution. Missing singletons/documents return `null`; empty pages
+return `[]`. `.execute()` returns the result envelope, including pagination
+and diagnostics, when an application needs those details.
+
+For a selection shared by several components, use the generated identity helper
+instead of recreating a query abstraction:
+
+```ts
+import { defineSelection } from '@/generated/storystick/query'
+
+export const postCard = defineSelection('blogPost', {
+  title: true,
+  slug: true,
+  coverImage: true,
+})
+```
+
+`client.query('blogPost').select(postCard)` keeps the exact selected result
+type. The helper emits no query syntax and adds no runtime work.
+
+Configured server reads carry public edit addresses with their values in authorized
+Preview. Ordinary async components, including later JSX descendants, need no
+render wrapper or query registration. A global projected-generation subscription
+refreshes the native Next tree, including queries that previously returned null
+or an empty array. Changes are grouped in a fixed 50ms window; another refresh
+waits for the current React transition. Stale projections do not trigger reads.
+This updates more of the server tree than mounted-query targeting.
+
+Keep stable React keys and native layout placement to retain client state.
+Preview strings contain invisible provenance: use a cleaned copy for string
+comparisons, lengths and other computation, and `previewTextProps` for native
+text elements (see below). Derived values have no guessed edit target. Images,
+links, rich text and slices retain the existing renderer helpers; custom
+non-text surfaces can use explicit edit attributes.
+
+## Optional CMS pages
+
+```tsx
+import { notFound, redirect, permanentRedirect } from 'next/navigation'
+import { site } from '@/lib/site'
+import { PageContent } from '@/components/page-content'
+
+type Props = {
+  params: Promise<{ pathname?: string[] }>
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}
+
+export default async function Page(props: Props) {
+  const route = await site.resolvePage(props)
+  if (route.type === 'redirect') {
+    const navigate = route.permanent ? permanentRedirect : redirect
+    navigate(route.redirectTo)
+  }
+  if (route.type !== 'document') notFound()
+  return <PageContent document={route.document} />
+}
+
+export async function generateMetadata(props: Props) {
+  const route = await site.resolvePage(props)
+  return site.metadata(route, route.type === 'document'
+    ? { title: route.document.fields.title } : {})
+}
+export const generateStaticParams = site.params
+```
+
+`PageContent` is application code. `resolvePage` accepts native catch-all props
+or explicit `{ pathname, searchParams }`. Native-props redirects retain query
+parameters. Public pages do not consume dynamic search parameters unless needed
+for a redirect. `site.metadata` cleans metadata and sets localized alternates,
+canonical URLs and Preview noindex. Sitemaps use `site.sitemapIds()` and
+`site.sitemap()`. Use native `error.tsx` for render failures. If an error boundary
+can replace the layout containing `<Storystick />`, mount
+`<StorystickErrorRecovery error={error} reset={reset} />` beside its fallback UI:
+
+```tsx
+'use client'
+import { StorystickErrorRecovery } from '@storystick/next'
+
+export default function ErrorPage({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  return <main role="alert">
+    <StorystickErrorRecovery error={error} reset={reset} />
+    <p>This page could not be displayed.</p>
+    <button onClick={reset}>Try again</button>
+  </main>
+}
+```
+
+This keeps Studio navigation available after a render failure, including moves
+between a route-less draft and the homepage. Passing `error` preserves the
+distinction between transient content-service failures (which Studio can recover) and customer rendering bugs (which are not
+automatically retried), including in production where Next redacts error details.
+Ordinary public visits do not load the Preview runtime. Startup failures that prevent the error component itself from
+mounting still require a full reload after the underlying problem is fixed.
+
+A native route needs neither a CMS document nor a catch-all. It keeps its own
+metadata responsibility; `storystickPreviewRobots({ enabled })` is available
+when handling metadata outside the CMS route helper. `site.page`,
+`site.component`, `StorystickDocument` and `StorystickEditable` are removed.
+
+See the [published language routes and resource mirror recipes](recipes/README.md)
+for `site.alternates()`, translated paths, `publicOrigins` / `domainLocale`, and an
+explicit French interface with an English fallback publication.
+
+## Layouts, locales and Preview
+
+`site.client()` uses the project's primary locale; `site.client({ locale })`
+selects another explicitly. Slice reads inherit their source document locale.
+For multilingual `<html lang>`, put the layout at a native segment that owns
+the language parameter. A root layout does not receive descendant parameters.
+Headers and footers can remain in their layouts and retain local client state.
+They remain editable on native routes without CMS page documents. Selecting
+a field changes the Studio editor target while retaining the actual view.
+
+The standard Preview integration shares one authorized reading perspective
+per browser/project/origin. Each view retains its own navigation and edit
+target. Variant/release selection changes the shared perspective; individual
+URLs are not its authority. No middleware, proxy, generated webpack alias,
+customer-link rewrite or provenance flag is required.
+
+Routing, read observations and JSON metadata live in framework-neutral
+packages. This package supplies the Next request and router adapter; it does
+not imply that Astro, Vue or Svelte adapters have been released.
+
+The root entry exposes the ordinary rendering and client surfaces:
+
+```tsx
+import {
+  previewTextProps,
+  RichText,
+  SliceZone,
+  StorystickImage,
+  StorystickLink,
+} from '@storystick/next'
+```
+
+Direct subpaths remain available as explicit bundle boundaries, but the starter
+and ordinary application code need only `@storystick/next`.
+
+## Render text fields
+
+SDK reads return native strings, including their provenance during authorized
+Preview. Move that metadata out of the text node when rendering a field:
+
+```tsx
+import { previewTextProps } from '@storystick/next'
+
+<h1 {...previewTextProps(fields.title)} />
+```
+
+`previewTextProps` returns plain `children` and a `data-ss-p` attribute for one
+complete field. It adds no wrapper, provider or client lifecycle, and its props
+can cross a Server Component boundary. The runtime validates the provenance
+before making the existing element an edit target. Plain production values
+produce only `children`.
+
+In client components that only need this helper, use
+`import { previewTextProps } from '@storystick/next/preview-text'` to keep the
+import limited to the pure text adapter. The root export remains available
+alongside the SDK's other rendering primitives.
+
+Use the original field before formatting or concatenation. A composite value
+is cleaned without assigning the element to a guessed field. Render fields
+on separate elements for separate targets; for transformed text, clean the
+display value and use explicit field bindings when an edit target is needed.
+Rendering a provenance-bearing string directly in JSX does not guarantee
+visually identical text across browsers and typography settings.
+
+## Clean values before computation and attributes
+
+String comparison is the first case to protect because a failed comparison
+leaves no detectable browser signal. Compare a cleaned copy, and pass the
+original field to `previewTextProps` to retain its edit target:
+
+```tsx
+import { previewTextProps, stripPreviewProvenance } from '@storystick/next'
+
+function ComparisonCell({ value }: { value: string }) {
+  const comparable = stripPreviewProvenance(value)
+  if (comparable === '✓') return <CheckIcon />
+  return <span {...previewTextProps(value)} />
+}
+```
+
+Use `stripPreviewProvenance(value)` before comparisons, custom attributes,
+`placeholder`, `aria-*`, custom metadata, JSON-LD, or another structured
+payload. The helper deep-copies JSON-shaped input, removes preview coded-text
+payloads and the reserved `_ssMarker` / `__ssPreviewProvenance` keys, and never
+mutates the source. It is client-compatible from `@storystick/next` and is also
+re-exported by `@storystick/next/server` for server-only code.
+
+Cleaning a field before passing it to `previewTextProps` removes its edit
+target. Keep the original value for that helper and clean separate copies for
+computation and other sinks.
+
+## Render image fields
+
+The zero-config component reads the request-owned asset sidecar registered by
+`resolvePage`, so an ordinary render only passes the field value:
+
+```tsx
+import { StorystickImage } from '@storystick/next'
+
+return (
+  <StorystickImage
+    image={fields.image}
+    loading="eager"
+    fetchPriority="high"
+  />
+)
+```
+
+Images are lazy and responsive by default, using a bounded `srcset` and
+`sizes="auto, 100vw"`. Eager images use `100vw`; set `responsive={false}` for
+a single source or pass `options.sizes` when the layout has a more precise
+contract. An explicit `source` remains authoritative for rendering outside a bound
+request: `options={{ source: assets }}`. Transformations, `widths` and `sizes`
+all live in this single options object. An explicit top-level `alt` overrides
+the field; `alt=""` remains decorative.
+
+A valid version LQIP is consumed automatically and removed after the final
+image decodes. Use `placeholder="none"` to opt out. Without an LQIP the
+component remains a server-rendered native `<img>` with no client lifecycle.
+When `sizes` is present without `widths`, Storystick emits its bounded standard
+responsive scale capped to the intrinsic asset width.
+
+Native events and React 19 refs are supported inside your Client Components,
+including when the image uses an LQIP. Functions still cannot cross a Server
+Component boundary: create handlers in a Client Component, or pass the plain
+JSON from `resolveImage().props` to your own client renderer.
+
+In development a non-renderable image logs a warning and leaves an inspectable
+`[data-storystick-image-status]` element at its render position. In production
+it renders `null` by default. Pass `fallback` for app-owned degradation in both
+environments; a render function receives the discriminated resolver failure:
+
+```tsx
+<StorystickImage
+  image={fields.coverImage}
+  fallback={({ status }) => <CoverPlaceholder reason={status} />}
+/>
+```
+
+`getNextImageProps()` remains available for explicit `next/image` interop. It
+is not the default path: Storystick already serves canonical provider-native
+transform URLs and avoids remote-pattern configuration and double optimization.
+
+### Optional `next/image` loader
+
+Storystick's default `<img>` path already serves provider-native canonical
+URLs. If an app needs a `next/image` loader, keep it pure: rewrite only the
+last transform-key segment, round the requested width up through the grammar,
+and map Next's numeric quality onto the three finite cache tiers.
+
+```ts
+import type { ImageLoaderProps } from 'next/image'
+import {
+  buildImageTransformKey,
+  parseImageTransformKey,
+  roundUpImageDimensionBucket,
+  type CanonicalImageTransform,
+  type ImageTransformQuality,
+} from '@storystick/asset-grammar'
+
+function qualityTier(quality = 75): ImageTransformQuality {
+  if (quality <= 55) return 'low'
+  if (quality <= 77) return 'medium'
+  return 'high'
+}
+
+export function storystickImageLoader({
+  src,
+  width,
+  quality,
+}: ImageLoaderProps): string {
+  const bucket = roundUpImageDimensionBucket(width)
+  if (bucket === null) throw new Error('Unsupported Storystick image width')
+
+  const url = new URL(src)
+  const path = url.pathname.split('/')
+  const encodedKey = path.pop()
+  if (!encodedKey) throw new Error('Missing Storystick transform key')
+
+  const parsed = parseImageTransformKey(decodeURIComponent(encodedKey))
+  const transform: CanonicalImageTransform =
+    parsed.kind === 'transform'
+      ? parsed.transform
+      : { schemaVersion: 1 }
+  const nextKey = buildImageTransformKey({
+    ...transform,
+    resize: {
+      width: bucket,
+      fit: transform.resize?.fit ?? 'scale-down',
+    },
+    quality: qualityTier(quality),
+  })
+
+  path.push(encodeURIComponent(nextKey))
+  url.pathname = path.join('/')
+  return url.toString()
+}
+```
+
+Install `@storystick/asset-grammar` directly when using this recipe. Bucket
+rounding fails closed above the largest supported width instead of creating an
+unbounded transformation key.
+
+## Advanced server integration
+
+`createServerClient` and `resolvePage` remain available from
+`@storystick/next/server`. They require
+explicit schema/site information that `createSite` binds once. Prefer direct
+Query V2 reads to route-wide data declarations when slices have different
+filters or selections.
+
+There is no `ss` namespace. Use `site.params()`, `site.sitemap()` and
+`site.sitemapIds()` for the configured site. Read singletons with
+`(await site.client()).query('settings').selectAll().fetch()`. Custom static
+parameters use paginated Query V2 selections and your own mapping, rather
+than a predefined `slug` field or segment name.
+
+Locale information is explicit: `route.localeContext` comes from
+`site.resolvePage()`, and `site.client({ locale })` configures an independent
+reader. The pure `prefixHref(href, locale, settings)` helper from
+`prefixHref`, re-exported by `@storystick/next`, builds localized links. It does not
+require another component to resolve a page first. Native layouts can pass
+this information through ordinary props or application context.
+
+`resolvePreviewDraft({ sessionId, locale? })` and
+`isPreviewDraftActive(sessionId)` are advanced draft-target helpers for a
+native page that already owns a view selector. They do not infer the request
+URL from private headers. Layout content does not need either helper.
+
+## HTTP routes and deployment
+
+`site.handlers` wraps `createRouteHandler` from `@storystick/next/preview`.
+It handles activation, access renewal, view context commands, exit, health,
+Preview runtime delivery and signed revalidation. `createSite({ routes })`
+accepts the same handler options; direct handler construction remains possible.
+
+Activation verifies the origin and capability, enables Draft Mode, and stores a
+signed HttpOnly admission for the project and customer origin. This admission
+**authorizes access; it does not select a perspective**. Each opening from Studio
+creates a navigation view attached to the authenticated project's current
+perspective. The URL's `_ss_session` identifies the view for navigation and
+selection; ordinary links do not need to carry it. Reopening or returning to
+Studio observes the shared perspective without replaying an old launch.
+Document write targets are still derived from the selected perspective, document,
+locale and release membership.
+
+### Navigation and perspectives
+
+Use ordinary `next/link` or `<a>` links, and `StorystickLink` for CMS links.
+The existing `<Storystick />` mount and Preview handlers own the integration:
+no Preview navigation provider, middleware, session prop or per-link helper is required.
+The SDK never rewrites customer DOM.
+
+A human authentication session shares one perspective per project and customer
+origin. Studio and detached previews observe the same revision; their current
+page, locale and field selection remain local. Layouts and pages read that
+perspective through the existing admission. Public requests retain static/ISR
+rendering; admitted Preview reads stay outside public caches.
+
+Choose **Published** in the perspective selector to read active publications
+while keeping the toolbar. Published uses the current frontend build with
+published content, without draft substitution or optimistic edits. A document or
+language without a publication remains unavailable. Choose Main, a variant or a
+release to resume editing. Changing perspective never publishes content.
+
+Perspective commands use compare-and-set revisions and idempotent receipts.
+A conflicting command is reported instead of silently replayed. Other surfaces
+adopt the observed perspective after preserving their pending edits in their
+original scope. Closing a panel does not end the shared context.
+
+Production Preview requires HTTPS and an allowed customer origin. Grants are
+addressed by project and normalized browser origin (including port), with the
+configured base path as the cookie path. Reopen existing previews after this
+upgrade so that their grants attach to the shared authority. Next Draft Mode is
+an infrastructure flag, not authorization for private content. Published keeps
+this admission active; it does not call the disable handler. Reopen from Studio
+after deploying a new application build.
+
+For simultaneous production Previews of separate Next builds, use distinct
+hostnames. Next's own `__prerender_bypass` cookie is shared by hostname, uses
+`Path=/`, and is bound to a build; another application on a different port or
+base path can replace it. Storystick preserves Next's production static/ISR gate
+and does not rename or emulate this framework cookie. Development and explicit
+local lanes read the addressed Storystick grant directly.
+
+For a custom native page outside the CMS route helper, metadata and native error handling
+remain application-owned. For non-DOM transformations of rendered content,
+keep the explicit cleaning boundary described above.
+
+Signed publish webhooks use `STORYSTICK_WEBHOOK_SECRET`. Keep that value and
+`STORYSTICK_API_KEY` server-only. Reverse proxies must preserve the customer
+origin through trusted forwarded host/protocol headers. No proxy is required
+by the SDK itself, and server action origin settings are not a replacement
+for configuring the proxy correctly.
+
+Licensed under [FSL-1.1-MIT](./LICENSE).
+
+### Rendering independent content
+
+Values returned by `site.client()` and `site.resolvePage()` already own their
+rendering dependencies. Use `<SliceZone slices={document.fields.sections}
+components={components} />` and `<RichText content={author.fields.bio} />` without
+technical context. Optional `context={{ document, parent }}` is application data
+only. Native layouts and async components remain ordinary Next components;
+no document wrapper or additional Provider is needed.
+
+Richtext is a JSON object on reads. Reserved content metadata survives JSON/RSC
+transport and must be preserved when passing rendering values. Component
+registries contain functions: import the registry in its rendering environment,
+rather than passing server functions through a client boundary.
+
+Async slice functions inherit the locale carried by their content, including
+nested slices and rich-text embeds. Awaited helpers inside that function share
+the same locale. Independent components rendered later use the site's default,
+or `site.client({ locale })`; no layout-global locale is assumed. Application
+`context` is never inspected for SDK locale selection.
+
+Automatic cache tags are bounded and share their encoding with invalidation.
+Custom tags retain Next's 256-character limit, with at most 127 distinct custom
+tags so every read can keep its project invalidation tag. Excess automatic tags
+are omitted only when project invalidation still covers the read.
+
+Public Query V2 delivery can use `STORYSTICK_DELIVERY_ENDPOINT`. Public framework
+reads now default to `no-store`; explicit Next Data Cache requires a finite
+positive `next.revalidate`. Publication handlers accept the shared v2 ready event,
+and `signWebhookBody` is asynchronous. For renderer-owned receipts, deployment
+manifests, recovery and qualified modes, see the repository's
+[publication contract](../../services/public-content-gateway/PUBLICATION.md).
+
+For ordinary static publication, declare `createSite({ definition,
+publicRendering: 'static' })` and supply a new `VERCEL_DEPLOYMENT_ID` or
+`STORYSTICK_DEPLOYMENT_ID` for **every compilation**, including CMS-only rebuilds
+of the same Git commit. Freeze it in the compiled artifact, for example using
+Next's `env` configuration. This mode keeps Next's native build-time caching
+and scopes content, locale and route-inventory fetches to that deployment, so a
+restored `.next/cache` cannot serve a previous build's content. Do not use the Git
+SHA as this identity or reuse an ID for a new compilation. Pages and sitemap
+must be activated together. Preview and explicit fresh reads remain `no-store`;
+do not use `dynamic = 'force-static'` on pages that support Draft Mode. Static
+publication still needs an actual rebuild and rendered proof, and does not
+qualify managed schema migration.
+
+The repository checks this against the actual marketing app with
+`node scripts/marketing-build-qualification.mjs --cache-rebuild`: retained fetch
+cache, changed content/locales/routes/sitemap, then a content-origin outage that
+must fail the next build. See the [Next 15 cache behavior](https://nextjs.org/docs/15/app/guides/caching).
+
+## Candidate distribution contract
+
+See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
+the qualified runtime matrix and the candidate cohort. Upgrade Storystick
+packages together.

package/dist/.source-hash

@@ -0,0 +1 @@
+20e8248dcde770c1a3966e62bbd395af132defa0ac1ada5c01ce32f486997919

package/dist/cache-tags.d.ts

@@ -0,0 +1,2 @@
+/** Internal tags share one bounded representation at read and invalidation. */
+export declare function storystickCacheTag(tag: string): string;