@storypane/sdk 0.1.0-rc.2 → 0.1.0-rc.3

package/README.md

@@ -12,15 +12,24 @@ Start with the [Next.js integration guide](https://github.com/lkuich/storypane/b
 server-side fetching, typed block components, and a separate live preview route.
 An [Astro example](https://github.com/lkuich/storypane/blob/main/apps/example-astro/README.md) is also included.
 
-The current version is **0.1.0-rc.2**. Use the SDK tarball attached to the
-[matching GitHub prerelease](https://github.com/lkuich/storypane/releases), or build
-from this monorepo with `pnpm --filter @storypane/sdk build` and pack/link
-`packages/sdk`. npm publication is separately gated on publisher setup; when
-available, select the explicit RC version or `@storypane/sdk@rc`. See the
-[release guide](https://storypane.dev/docs/releases-and-versioning/). Install the release artifact without waiting for npm publication:
+The current version is **0.1.0-rc.3**, published on npm as a release candidate:
 
 ```sh
-npm install https://github.com/lkuich/storypane/releases/download/v0.1.0-rc.2/storypane-sdk-0.1.0-rc.2.tgz
+npm install @storypane/sdk@0.1.0-rc.3
+# Or follow the candidate channel:
+npm install @storypane/sdk@rc
+```
+
+Pin the explicit version for reproducible builds. npm also assigned `latest` to
+this first publication; that tag does not make it stable. See the
+[release guide](https://storypane.dev/docs/releases-and-versioning/) for status,
+upgrades, and known limits.
+
+You can also build from this monorepo with `pnpm --filter @storypane/sdk build`
+and pack/link `packages/sdk`, or install the verified GitHub archive:
+
+```sh
+npm install https://github.com/lkuich/storypane/releases/download/v0.1.0-rc.3/storypane-sdk-0.1.0-rc.3.tgz
 ```
 
 Entrypoints:
@@ -42,6 +51,12 @@ The root locale contributes an empty path segment; the editor removes doubled
 slashes. `{slug}` is the selected locale's URL slug. Query placeholders also work:
 `https://site.example/preview?slug={slug}&locale={locale}`.
 
+Admins set the **Space default** preview URL. Each member can save **My default
+preview** in the same settings screen, or choose **Use space default**. This
+preference follows the user across browsers in that space. Editor and component
+previews use it unless another URL is selected in the editor. Server-created
+preview sessions continue to use the space default unless `previewId` is provided.
+
 The default preview parameter is `storypane_preview=1`. You can change its name in
 settings; use the same name in your SDK options. Your app must permit the CMS
 origin in its CSP `frame-ancestors` policy and must not send a conflicting
@@ -174,6 +189,61 @@ The [complete Next.js example](https://github.com/lkuich/storypane/blob/main/app
 It keeps published pages on the server and reuses the renderer inside `/preview`.
 Client preview components must not import server-only fetch modules.
 
+### Block hover previews
+
+Component previews are available starting with `@storypane/sdk@0.1.0-rc.3`.
+
+The editor can preview saved blocks and the add-block picker's sample content in
+one temporary iframe after a short hover or keyboard focus. It uses the selected
+preview URL and the same authenticated, read-only flow as the full preview.
+Escape dismisses the preview. Nothing is inserted or saved by hovering.
+
+Opt in by passing a stable `onComponent` callback to `useStorypanePreview`,
+`useStorypaneStory`, or `connectPreview`. Render that block alone with your existing
+component renderer, without page navigation or preview status chrome:
+
+```tsx
+const [component, setComponent] = useState<StorypaneComponent>();
+const { story } = useStorypanePreview<StorypaneComponent>({
+  cmsUrl,
+  spaceId,
+  story: { slug, locale },
+  onComponent: setComponent,
+});
+// Keep passing the story's references and other renderer context as usual.
+if (story) return <Block block={component ?? story.content} />;
+```
+
+Use the generated `StorypaneComponent` union here: picker previews include nestable
+blocks as well as content types. Both example apps demonstrate this integration.
+Picker previews are opt-in per definition: set **Config → Picker preview data (JSON)**
+and deploy the schema migration. This stores an optional `previewData` object with
+sample field values; nested blocks use `{ _uid, component, ...fields }`. Use real
+representative content, including the nested items your renderer needs. A definition
+without sample data has no picker preview. Samples override defaults for this iframe
+only; inserting a block still uses its normal field defaults.
+
+For example, a feature grid can have this preview data:
+
+```json
+{
+  "title": "A fresh perspective",
+  "items": [
+    { "_uid": "preview-feature", "component": "feature", "title": "Start with a good question." }
+  ]
+}
+```
+
+Samples are validated against field types and allowed nested blocks, limited to
+100 KB per definition, and included in full schema migrations. Referenced original
+media follows the existing clone/sync/promotion dependency review. They are excluded
+from delivery schema metadata and generated component types. Both examples keep
+editable fixtures in `storypane/preview-data.json`; the Astro setup script installs
+them into newly seeded spaces. For an existing space, copy each fixture into that
+block's Config tab and deploy the migration.
+
+Existing integrations without `onComponent` keep full-page preview and show a setup message for hover previews.
+
 If you prefer preview on an existing published route, `useStorypaneStory(initial,
 options)` remains available. It starts with the publication and activates drafts
 only when its `mode` matches. For Next.js Draft Mode, pass the server's `isEnabled`
@@ -642,7 +712,15 @@ authenticated `getAsset` integration for static export when public media is disa
 
 ## MCP
 
-Run `storypane mcp` (Node 20+) with `STORYPANE_URL`, `STORYPANE_SPACE_ID`, and a
-private `STORYPANE_MANAGEMENT_TOKEN`. The stdio adapter exposes read and write
+Launch the pinned package directly (Node 20+), with `STORYPANE_URL`,
+`STORYPANE_SPACE_ID`, and a private `STORYPANE_MANAGEMENT_TOKEN` configured in
+your MCP client's environment:
+
+```sh
+npx --yes --package=@storypane/sdk@0.1.0-rc.3 storypane mcp
+```
+
+If installed in your project, `pnpm exec storypane mcp` also works from its root.
+The stdio adapter exposes read and write
 tools over the management API; the same scopes, issuer permissions and revocation
 apply. See [MCP configuration and contracts](https://github.com/lkuich/storypane/blob/main/docs/management-api.md#mcp-adapter).

package/dist/preview.d.ts

@@ -9,6 +9,8 @@ export interface PreviewOptions<T = StorypaneStory['content']> {
     story: StoryReference;
     mode?: PreviewMode;
     onChange: (story: StorypaneStory<T>) => void;
+    /** Opt in to isolated block previews using the same component renderer as your site. */
+    onComponent?: (block: T | undefined) => void;
     onStatus?: (status: PreviewStatus, error?: Error) => void;
     /** For standalone preview, fetch a short-lived session from your authenticated app server. */
     getSession?: () => Promise<PreviewSession>;

package/dist/preview.js

@@ -13,6 +13,8 @@ export function connectPreview(options) {
     let reconnect, renew;
     let ready, retry = 0, revision = -1, selected = '';
     let referencesRevision;
+    let content;
+    let component;
     const embedded = window.parent !== window;
     const send = (message) => {
         if (embedded)
@@ -39,6 +41,31 @@ export function connectPreview(options) {
                 element.removeAttribute('data-storypane-selected');
         }
     }
+    function renderComponent() {
+        if (!component ||
+            !options.onComponent ||
+            !session ||
+            Date.parse(session.expiresAt) <= Date.now() ||
+            content === undefined)
+            return;
+        function find(value, id) {
+            if (!value || typeof value !== 'object')
+                return;
+            if ('_uid' in value &&
+                value._uid === id &&
+                'component' in value &&
+                typeof value.component === 'string')
+                return value;
+            for (const child of Object.values(value)) {
+                const found = find(child, id);
+                if (found)
+                    return found;
+            }
+        }
+        const block = 'block' in component ? component.block : find(content, component.blockId);
+        options.onComponent(block);
+        send({ type: 'storypane:component-rendered', found: !!block });
+    }
     function open(value) {
         if (stopped || !matches(value))
             return;
@@ -77,6 +104,8 @@ export function connectPreview(options) {
                     revision = message.story.revision;
                     referencesRevision = message.story.referencesRevision;
                     options.onChange(message.story);
+                    content = message.story.content;
+                    renderComponent();
                     highlight();
                 }
                 else if (message.type === 'error')
@@ -114,12 +143,14 @@ export function connectPreview(options) {
             else if (embedded) {
                 send({
                     type: 'storypane:ready',
+                    componentPreview: !!options.onComponent,
                     spaceId: options.spaceId,
                     ...options.story,
                 });
                 if (!ready)
                     ready = setInterval(() => send({
                         type: 'storypane:ready',
+                        componentPreview: !!options.onComponent,
                         spaceId: options.spaceId,
                         ...options.story,
                     }), 3000);
@@ -137,6 +168,16 @@ export function connectPreview(options) {
             return;
         if (event.data?.type === 'storypane:init')
             open(event.data.session);
+        if (event.data?.type === 'storypane:component' && options.onComponent) {
+            const { blockId, block } = event.data;
+            if (typeof blockId === 'string')
+                component = { blockId };
+            else if (block && typeof block._uid === 'string' && typeof block.component === 'string')
+                component = { block };
+            else
+                return;
+            renderComponent();
+        }
         if (event.data?.type === 'storypane:select' && typeof event.data.blockId === 'string') {
             selected = event.data.blockId;
             highlight();
@@ -186,6 +227,8 @@ export function connectPreview(options) {
     void authorize();
     return () => {
         stopped = true;
+        if (component)
+            options.onComponent?.(undefined);
         if (socket) {
             socket.onclose = null;
             socket.close();

package/dist/react.d.ts

@@ -2,7 +2,7 @@ import { type PreviewOptions, type PreviewStatus } from './preview.js';
 import type { StorypaneStory, StoryReference } from './types.js';
 export { editable } from './types.js';
 /** Preview a story that may never have been published. The editor supplies its short-lived session. */
-export declare function useStorypanePreview<T = StorypaneStory['content']>({ story: reference, cmsUrl, spaceId, migrationVersion, getSession, }: Omit<PreviewOptions<T>, 'story' | 'mode' | 'onChange' | 'onStatus'> & {
+export declare function useStorypanePreview<T = StorypaneStory['content']>({ story: reference, cmsUrl, spaceId, migrationVersion, getSession, onComponent, }: Omit<PreviewOptions<T>, 'story' | 'mode' | 'onChange' | 'onStatus'> & {
     story?: StoryReference;
 }): {
     story: StorypaneStory<T> | undefined;

package/dist/react.js

@@ -3,7 +3,7 @@ import { useEffect, useRef, useState } from 'react';
 import { connectPreview } from './preview.js';
 export { editable } from './types.js';
 /** Preview a story that may never have been published. The editor supplies its short-lived session. */
-export function useStorypanePreview({ story: reference, cmsUrl, spaceId, migrationVersion, getSession, }) {
+export function useStorypanePreview({ story: reference, cmsUrl, spaceId, migrationVersion, getSession, onComponent, }) {
     const id = reference?.id;
     const slug = reference?.slug;
     const locale = reference?.locale;
@@ -20,12 +20,13 @@ export function useStorypanePreview({ story: reference, cmsUrl, spaceId, migrati
             spaceId,
             migrationVersion,
             getSession,
+            onComponent,
             story: id ? { id, locale } : { slug: slug, locale },
             mode: { draft: true },
             onChange: (story) => setResult((current) => ({ ...current, key, story })),
             onStatus: (status, error) => setResult((current) => ({ ...current, key, status, error })),
         });
-    }, [cmsUrl, spaceId, id, slug, locale, migrationVersion, getSession, key]);
+    }, [cmsUrl, spaceId, id, slug, locale, migrationVersion, getSession, onComponent, key]);
     // Never display the previous story while a new route is authorizing.
     const current = result.key === key
         ? result
@@ -48,6 +49,7 @@ export function useStorypaneStory(initial, options) {
         story: { id: initial.id, locale: initial.locale },
         mode: JSON.parse(mode),
         getSession: options.getSession,
+        onComponent: options.onComponent,
         onChange: setStory,
         onStatus: (value, cause) => {
             setStatus(value);
@@ -60,6 +62,7 @@ export function useStorypaneStory(initial, options) {
         options.spaceId,
         options.migrationVersion,
         options.getSession,
+        options.onComponent,
         mode,
     ]);
     return { story, status, error };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storypane/sdk",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "type": "module",
   "description": "Published content delivery and live visual preview for Storypane",
   "files": [