@storystick/react 0.0.0-stage → 0.2.0-rc.0

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/NOTICE

@@ -0,0 +1,17 @@
+Preview control icon geometries are derived from lucide-react 0.469.0.
+
+ISC License
+
+Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as part of Feather (MIT). All other copyright (c) for Lucide are held by Lucide Contributors 2022.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/PUBLIC-API.md

@@ -0,0 +1,36 @@
+# @storystick/react API contract
+
+Install this candidate explicitly with `@storystick/react@0.2.0-rc.0` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+
+Version 0.2.0-rc.0, cohort `sdk-0.2.0-rc.0`. 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 |
+| `./slice` | Supported beta entry |
+| `./link` | Supported beta entry |
+| `./query` | Supported beta entry |
+| `./rich-text` | Supported beta entry |
+| `./slice-zone` | Supported beta entry |
+| `./internal/preview-provenance` | Reserved SDK contract |
+| `./internal/link-adapter` | Reserved SDK contract |
+| `./internal/storystick-mark` | Reserved SDK contract |
+| `./internal/preview-interaction-control` | Reserved SDK contract |
+| `./internal/use-preview-perspective-intent` | Reserved SDK contract |
+| `./internal/use-momentary-preview-navigate-mode` | Reserved SDK contract |
+| `./internal/resize-edge` | Reserved SDK contract |
+| `./internal/preview-toolbar-shell` | Reserved SDK contract |
+| `./internal/preview-panel-state` | Reserved SDK contract |
+| `./internal/preview-host` | Reserved SDK contract |
+
+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,227 @@
-# Temporary Holding Version
+# @storystick/react
 
-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.
+React 19 rendering primitives and a provider-free hook for generated Query V2 reads.
+
+```bash
+pnpm add @storystick/react@beta react@19.2.8 react-dom@19.2.8
+```
+
+Run `storystick generate` first; it writes
+`generated/storystick/query.ts`. Then create a client with that schema, build a
+query, and pass the executable query directly to `useQuery`. No query provider
+is required.
+
+```tsx
+'use client'
+
+import { createClient, previewTextProps } from '@storystick/react'
+import { useQuery } from '@storystick/react/query'
+import { querySchema } from '@/generated/storystick/query'
+
+const client = createClient({
+  schema: querySchema,
+  projectId: process.env.NEXT_PUBLIC_STORYSTICK_PROJECT_ID!,
+  publishableKey: process.env.NEXT_PUBLIC_STORYSTICK_PUBLISHABLE_KEY!,
+})
+
+const latestPosts = client
+  .query('blogPost')
+  .select({ title: true, slug: true })
+  .orderBy((fields, { desc }) => [desc(fields.publishedAt)])
+  .page({ first: 20 })
+
+export function LatestPosts() {
+  const result = useQuery(latestPosts)
+
+  if (result.status === 'pending') return <p>Loading…</p>
+  if (result.status === 'error') return <p>{result.error.message}</p>
+
+  return (
+    <ul>
+      {result.data.map((post) => (
+        <li key={post.documentId} {...previewTextProps(post.fields.title)} />
+      ))}
+    </ul>
+  )
+}
+```
+
+The query owns its generated schema and production client identity. Inside a
+trusted Storystick Preview session, `useQuery` automatically executes the same
+compiled query through the current living, variant, or release authority and
+returns to production when Preview ends. Preview tokens never enter the query
+key or component props.
+
+`SliceZone`, `RichText`, links and media components are available from the same
+root entry. Subpaths remain available when an application wants an explicit
+bundle boundary:
+
+```tsx
+import { useQuery } from '@storystick/react/query'
+import { RichText } from '@storystick/react/rich-text'
+import { SliceZone } from '@storystick/react/slice-zone'
+```
+
+The root entry contains rendering and client primitives. Import `useQuery` from
+`@storystick/react/query` so a render-only import never discovers the reactive
+Preview loader. This is an intentional pre-launch API change in the candidate cohort.
+
+Generated slice maps can type a whole registry without per-component casts:
+
+```tsx
+import { SliceZone, type SliceComponentRegistry } from '@storystick/react/slice-zone'
+import type { SliceTypeMap } from '@/generated/storystick/types'
+
+type LandingSliceMap = Pick<SliceTypeMap, 'hero' | 'cta'>
+
+const components = {
+  hero: Hero,
+  cta: Cta,
+} satisfies SliceComponentRegistry<LandingSliceMap>
+
+<SliceZone<LandingSliceMap>
+  slices={page.fields.sections}
+  components={components}
+  fallback={({ reason }) => (
+    <p data-slice-fallback={reason}>This section is unavailable.</p>
+  )}
+/>
+```
+
+Every generated slice carries its exact `_type`, `_key`, fields, and variation
+discriminator. A missing slice array is an ordinary empty render. Malformed or
+unregistered entries invoke `fallback` and emit a development diagnostic;
+production never has to discard them silently.
+
+## Render text fields
+
+SDK reads return native strings. During authorized Preview, those strings can
+carry edit provenance. In a component with queried `fields`, spread
+`previewTextProps` on the element that displays the original field:
+
+```tsx
+import { previewTextProps } from '@storystick/react'
+
+<h1 {...previewTextProps(fields.title)} />
+```
+
+The helper returns plain `children` and, when the value identifies one complete
+field, a `data-ss-p` attribute. Preview metadata stays in the attribute instead
+of the text node. No wrapper or client lifecycle is added. This avoids relying
+on browsers to render invisible codewords identically; raw JSX containing a
+Preview string is not guaranteed to remain visually unchanged across browsers.
+
+Client components that only need this helper can import it from
+`@storystick/react/preview-text`. This direct entry contains the pure text
+adapter without importing the SDK's query or renderer entry points.
+
+Pass the original field before formatting or concatenating it. Composed values
+are cleaned without choosing an edit target. Render each field on its own
+element when it needs a separate target, or use explicit field bindings for a
+custom presentation. Use `stripPreviewProvenance` on a copy before string
+computation, custom attributes or structured payloads.
+
+## Autonomous content and optional app context
+
+SDK reads prepare the content before components receive it. Models, bindings,
+links, assets and container zones resolve from that content's own origin:
+
+```tsx
+<SliceZone slices={page.fields.sections} components={components} />
+<RichText content={author.fields.bio} />
+<StorystickImage image={slice.image} />
+<StorystickLink link={slice.action} />
+```
+
+Import `Slice` from `@storystick/react` (or `@storystick/react/slice`).
+Keep `<Slice.section slice={slice}>` on a slice's visual root when you want its
+Preview overlay. This is an explicit attribute opt-in, not an extra DOM wrapper.
+An authored slice `_anchor` becomes the root's native `id` automatically.
+Default rich-text headings do the same; custom heading renderers receive an
+optional `id` to forward to their native heading element.
+
+`context` is only application data. The SDK passes it through without reading
+or adding keys. For example, when a child needs document and parent fields:
+
+```tsx
+<SliceZone slices={document.fields.sections} components={components}
+  context={{ document }} />
+
+function ContainerSlice({ slice, context }) {
+  return <Slice.section slice={slice}>
+    <SliceZone slices={slice.children} components={components}
+      context={{ ...context, parent: slice }} />
+  </Slice.section>
+}
+
+function Child({ slice, context }) {
+  return <Slice.section slice={slice}>
+    <h2 {...previewTextProps(context.document.fields.title)} />
+    <p {...previewTextProps(context.parent.heading)} />
+    <RichText content={slice.body} />
+  </Slice.section>
+}
+```
+
+Type application context with `SliceComponentProps<MySlice, MyContext>` when
+needed. No context is required for content resolution. An explicitly different
+query locale belongs on the client/query, not in an inferred `context.document`.
+
+A **Container Slice** owns `slice.children` and renders another `SliceZone`.
+A **Zone Container** arranges mapped fields of the host document: use
+`<ZoneSlot zone={zones?.main} />` and `<ZoneSlot zone={zones?.aside} />`. Those
+slots are already prepared and receive the caller's application context. The
+SDK does not inject `parent`. Existing nesting and model restrictions still apply.
+
+Generated `RichTextValue` is a JSON ProseMirror `doc` object, not a serialized
+string. Storage remains serialized. Do not `JSON.parse` SDK read values.
+SDK objects carry reserved `__ssContent` rendering metadata. Preserve it when
+passing content across JSON/RSC boundaries; arrays have no hidden properties.
+Filtering/reordering arrays and shallow-copying their elements preserve origin.
+Do not write rendering metadata back into editorial fields.
+
+For manually reconstructed/raw compositions, the advanced escape hatch is
+`source={{ document, path: 'sections' }}` on `SliceZone`, or
+`source={{ document, path: 'body' }}` on `RichText`. It performs no query.
+Contradicting an autonomous value's origin throws instead of silently borrowing
+another document. Pure media/link resolvers still accept explicit sidecars.
+A raw value with missing dependencies cannot obtain them from unrelated reads.
+
+Licensed under [FSL-1.1-MIT](./LICENSE).
+
+`Slice` only declares the visual root of a slice, including container slices
+and rich-text embeds. It requires `slice` and accepts the chosen element's
+native props. It does not bind documents or fields. For transformed text,
+clean the display value and spread the existing field attributes:
+
+```tsx
+import { Slice, stripPreviewProvenance } from '@storystick/react'
+
+function Heading({ slice, bindings }) {
+  return <Slice.section slice={slice}>
+    <h2 {...bindings?.fields.headline}>
+      {formatHeading(stripPreviewProvenance(slice.headline))}
+    </h2>
+  </Slice.section>
+}
+```
+
+These attributes are plain data and remain optional outside Preview.
+
+`StorystickImage` emits a lazy responsive native image by default, including a
+bounded `srcset` and `sizes="auto, 100vw"`. Use `responsive={false}` for a
+single source, or pass an explicit `options.sizes` for a known layout. Native
+media components accept events and React 19 refs when used in a Client
+Component. The resolvers remain available for custom native rendering.
+`useQuery` allocates observers only after commit; server rendering returns a
+stable pending snapshot without starting a fetch or a cache timer. Its Preview
+participation loads on activation and retains the existing targeted/live updates.
+The public result is deliberately conventional: `pending`, `success`, or
+`error`. Projection rebuilding and targeting remain internal, so applications
+do not need to model Content Plane convergence states.
+
+## 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 @@
+937895c9b9d8b1e9dd734b85c5339eee7d93c3afe545ac5d65f65f5330fb3acb

package/dist/file.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { type ResolveFileOptions, type ResolvedStorystickFile, type StorystickFileField } from '@storystick/media';
+/** Resolve a File field from an explicit or value-owned asset metadata. */
+export { resolveFile } from '@storystick/media';
+type FileAnchorProps = Omit<React.ComponentPropsWithRef<'a'>, 'href' | 'download' | 'type' | 'children'>;
+export type StorystickFileComponentProps = FileAnchorProps & {
+    file: StorystickFileField | null | undefined;
+    options?: ResolveFileOptions;
+    children?: React.ReactNode;
+    fallback?: StorystickFileFallback;
+};
+export type StorystickFileFailure = Exclude<ResolvedStorystickFile, {
+    readonly status: 'ok';
+}>;
+export type StorystickFileFallback = React.ReactNode | ((resolution: StorystickFileFailure) => React.ReactNode);
+/** Server-safe native download link with resolver-owned href and provenance. */
+export declare function StorystickFile(input: StorystickFileComponentProps): React.ReactElement | null;
+export type { FileStatus, ResolveFileOptions, ResolvedStorystickFile, StorystickFileField, StorystickFileProps, } from '@storystick/media';

package/dist/file.js

@@ -0,0 +1,44 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { emitMediaDiagnostic, isProduction } from '@storystick/media/internal/render-diagnostics';
+import { cleanPreviewAttributes } from '@storystick/types/internal/preview-provenance';
+import { resolveFile, } from '@storystick/media';
+/** Resolve a File field from an explicit or value-owned asset metadata. */
+export { resolveFile } from '@storystick/media';
+/** Server-safe native download link with resolver-owned href and provenance. */
+export function StorystickFile(input) {
+    const { file, options = {}, children, fallback, ...anchorProps } = input;
+    const diagnostics = [];
+    const resolved = resolveFile(file, {
+        ...options,
+        warn: (message) => diagnostics.push(message),
+    });
+    if (resolved.status !== 'ok') {
+        if (!isProduction() && resolved.status !== 'no-file') {
+            emitMediaDiagnostic(`StorystickWarning: file resolution status=${resolved.status}.${diagnostics.length > 0 ? ` ${diagnostics.join(' ')}` : ''}`, options.warn);
+        }
+        if (fallback !== undefined) {
+            return _jsx(_Fragment, { children: typeof fallback === 'function' ? fallback(resolved) : fallback });
+        }
+        if (isProduction() || resolved.status === 'no-file')
+            return null;
+        return (_jsx("span", { "aria-hidden": "true", "data-storystick-file-status": resolved.status, ...('data-ss-e' in resolved
+                ? { 'data-ss-e': resolved['data-ss-e'] }
+                : {}) }));
+    }
+    if (!isProduction()) {
+        for (const message of diagnostics)
+            emitMediaDiagnostic(message, options.warn);
+    }
+    return (_jsx("a", { ...fileAnchorProps(resolved.props, anchorProps), children: children ?? resolved.filename }));
+}
+function fileAnchorProps(resolved, input) {
+    return {
+        ...cleanPreviewAttributes(input),
+        href: resolved.href,
+        download: resolved.download,
+        ...(resolved.type ? { type: resolved.type } : {}),
+        ...('data-ss-e' in resolved
+            ? { 'data-ss-e': resolved['data-ss-e'] }
+            : {}),
+    };
+}

package/dist/hydrate-slice.d.ts

@@ -0,0 +1,3 @@
+export { hydrateSlice, hydrateSliceWithDiagnostics, getFieldBindings, resolveBinding, getByPath } from '@storystick/client/internal';
+export type { FieldBindingsSidecar, HydrateSliceOptions, SliceHydrationFailure, HydratedSliceResult } from '@storystick/client/internal';
+export type { SerializedModelSidecar } from '@storystick/types';

package/dist/hydrate-slice.js

@@ -0,0 +1 @@
+export { hydrateSlice, hydrateSliceWithDiagnostics, getFieldBindings, resolveBinding, getByPath } from '@storystick/client/internal';

package/dist/image-component.d.ts

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { type ResolveImageOptions, type ResolvedStorystickImage, type StorystickImageField } from '@storystick/media';
+type StorystickImageDomProps = Omit<React.ComponentPropsWithRef<'img'>, 'children' | 'dangerouslySetInnerHTML' | 'src' | 'alt' | 'width' | 'height' | 'srcSet' | 'sizes'>;
+export type StorystickImageComponentProps = StorystickImageDomProps & {
+    image: StorystickImageField | null | undefined;
+    /** Resolution and provider-native transformation options. */
+    options?: ResolveImageOptions;
+    /** Disable responsive candidates for constrained editor surfaces. */
+    responsive?: boolean;
+    /** Contextual alternative text. Empty string explicitly marks decoration. */
+    alt?: string;
+    /** Automatically consume the version LQIP unless explicitly disabled. */
+    placeholder?: 'auto' | 'none';
+    /** Customer-owned output for empty or non-renderable image states. */
+    fallback?: StorystickImageFallback;
+};
+export type StorystickImageFailure = Exclude<ResolvedStorystickImage, {
+    readonly status: 'ok';
+}>;
+export type StorystickImageFallback = React.ReactNode | ((resolution: StorystickImageFailure) => React.ReactNode);
+/**
+ * Framework-neutral native image renderer. It emits lazy responsive images by
+ * default while preserving provider transforms, LQIP and Preview provenance.
+ */
+export declare function StorystickImage(input: StorystickImageComponentProps): React.JSX.Element | null;
+export {};

package/dist/image-component.js

@@ -0,0 +1,79 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { emitMediaDiagnostic, isProduction } from '@storystick/media/internal/render-diagnostics';
+import { cleanPreviewAttributes } from '@storystick/types/internal/preview-provenance';
+import { resolveImage, } from '@storystick/media';
+import { StorystickImageElement } from './image-element.js';
+/**
+ * Framework-neutral native image renderer. It emits lazy responsive images by
+ * default while preserving provider transforms, LQIP and Preview provenance.
+ */
+export function StorystickImage(input) {
+    const { image, options = {}, responsive = true, alt, placeholder = 'auto', fallback, ...imgProps } = input;
+    const diagnostics = [];
+    const imageForResolve = alt !== undefined && image ? { ...image, alt } : image;
+    const defaultSizes = imgProps.loading === 'eager' ? '100vw' : 'auto, 100vw';
+    const resolved = resolveImage(imageForResolve, {
+        ...options,
+        ...(responsive && options.sizes === undefined ? { sizes: defaultSizes } : {}),
+        ...(!responsive ? { widths: [], sizes: undefined } : {}),
+        warn: (message) => diagnostics.push(message),
+    });
+    if (resolved.status !== 'ok') {
+        if (!isProduction() && resolved.status !== 'no-image') {
+            const detail = diagnostics.length > 0 ? ` ${diagnostics.join(' ')}` : '';
+            emitMediaDiagnostic(`StorystickWarning: image resolution status=${resolved.status}.${detail}`, options.warn);
+        }
+        if (fallback !== undefined) {
+            return _jsx(_Fragment, { children: typeof fallback === 'function' ? fallback(resolved) : fallback });
+        }
+        if (isProduction() || resolved.status === 'no-image')
+            return null;
+        return (_jsx("span", { "aria-hidden": "true", "data-storystick-image-status": resolved.status, ...('data-ss-e' in resolved
+                ? { 'data-ss-e': resolved['data-ss-e'] }
+                : {}) }));
+    }
+    if (!isProduction()) {
+        for (const message of diagnostics)
+            emitMediaDiagnostic(message, options.warn);
+    }
+    const props = imageElementProps(resolved.props, imgProps, responsive ? undefined : 'eager');
+    if (placeholder === 'none' || !resolved.blurDataURL) {
+        return _jsx("img", { ...props });
+    }
+    return (_jsx(StorystickImageElement, { ...props, blurDataURL: resolved.blurDataURL }, `${props.src}:${resolved.blurDataURL}`));
+}
+function imageElementProps(resolved, input, defaultLoading) {
+    const forwarded = { ...input };
+    const protectedProps = forwarded;
+    for (const key of [
+        'src',
+        'alt',
+        'width',
+        'height',
+        'srcSet',
+        'sizes',
+        'data-ss-e',
+        'children',
+        'dangerouslySetInnerHTML',
+    ]) {
+        delete protectedProps[key];
+    }
+    const style = resolved.style || input.style
+        ? { ...resolved.style, ...input.style }
+        : undefined;
+    return {
+        ...cleanPreviewAttributes(forwarded),
+        src: resolved.src,
+        alt: resolved.alt,
+        width: resolved.width,
+        height: resolved.height,
+        ...(resolved.srcSet ? { srcSet: resolved.srcSet } : {}),
+        ...(resolved.sizes ? { sizes: resolved.sizes } : {}),
+        loading: input.loading ?? defaultLoading ?? resolved.loading,
+        decoding: input.decoding ?? resolved.decoding,
+        ...(style ? { style } : {}),
+        ...('data-ss-e' in resolved
+            ? { 'data-ss-e': resolved['data-ss-e'] }
+            : {}),
+    };
+}

package/dist/image-element.d.ts

@@ -0,0 +1,6 @@
+import * as React from 'react';
+export type StorystickImageElementProps = React.ComponentPropsWithRef<'img'> & {
+    blurDataURL: string;
+};
+/** Owns only the lifecycle required to remove a server-painted LQIP. */
+export declare function StorystickImageElement({ blurDataURL, ref, onLoad, onError, src, style, ...props }: StorystickImageElementProps): React.JSX.Element;

package/dist/image-element.js

@@ -0,0 +1,68 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+/** Owns only the lifecycle required to remove a server-painted LQIP. */
+export function StorystickImageElement({ blurDataURL, ref, onLoad, onError, src, style, ...props }) {
+    const imageRef = React.useRef(null);
+    const mountedRef = React.useRef(false);
+    const srcKey = typeof src === 'string' ? src : '';
+    const currentSrcRef = React.useRef(srcKey);
+    currentSrcRef.current = srcKey;
+    const [settledSrc, setSettledSrc] = React.useState(null);
+    const showsPlaceholder = settledSrc !== srcKey;
+    const settle = React.useCallback(async (image) => {
+        const expectedSrc = srcKey;
+        if (typeof image.decode === 'function') {
+            try {
+                await image.decode();
+            }
+            catch {
+                // A failed decode must not leave the placeholder over native error UI.
+            }
+        }
+        if (!mountedRef.current || currentSrcRef.current !== expectedSrc)
+            return;
+        setSettledSrc(expectedSrc);
+    }, [srcKey]);
+    React.useEffect(() => {
+        mountedRef.current = true;
+        const image = imageRef.current;
+        if (image?.complete) {
+            void settle(image);
+        }
+        return () => {
+            mountedRef.current = false;
+        };
+    }, [settle]);
+    const setImageRef = React.useCallback((element) => {
+        imageRef.current = element;
+        const cleanup = typeof ref === 'function' ? ref(element) : undefined;
+        if (ref && typeof ref !== 'function')
+            ref.current = element;
+        return () => {
+            imageRef.current = null;
+            if (typeof cleanup === 'function')
+                cleanup();
+            else if (typeof ref === 'function')
+                ref(null);
+            else if (ref)
+                ref.current = null;
+        };
+    }, [ref]);
+    const placeholderStyle = showsPlaceholder
+        ? {
+            backgroundImage: `url(${JSON.stringify(blurDataURL)})`,
+            backgroundPosition: style?.objectPosition ?? 'center',
+            backgroundRepeat: 'no-repeat',
+            backgroundSize: 'cover',
+        }
+        : undefined;
+    return (_jsx("img", { ...props, ref: setImageRef, src: src, style: placeholderStyle ? { ...style, ...placeholderStyle } : style, onLoad: (event) => {
+            const image = event.currentTarget;
+            void settle(image);
+            onLoad?.(event);
+        }, onError: (event) => {
+            setSettledSrc(srcKey);
+            onError?.(event);
+        } }));
+}

package/dist/image.d.ts

@@ -0,0 +1,3 @@
+/** The media resolver owns both autonomous and explicitly sourced values. */
+export { resolveImage } from '@storystick/media';
+export { StorystickImage, type StorystickImageComponentProps, type StorystickImageFailure, type StorystickImageFallback, } from './image-component.js';

package/dist/image.js

@@ -0,0 +1,3 @@
+/** The media resolver owns both autonomous and explicitly sourced values. */
+export { resolveImage } from '@storystick/media';
+export { StorystickImage, } from './image-component.js';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './rendering.js';