nextpluggable 0.0.0-stage → 0.1.0

package/bin/nextpluggable.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import('../dist/cli.js')
+  .then((cli) => cli.main())
+  .then(
+    (code) => process.exit(code),
+    (err) => {
+      console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    },
+  );

package/dist/api/handler.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedConfig } from '../config.js';
+import { type SessionView } from '../views.js';
+export interface HandlerHooks {
+    /** Called after anything that changes what the public site renders. */
+    onSiteChange?: () => void | Promise<void>;
+}
+/** Header every dashboard/plugin write must carry. Browsers will not send it cross-site without a CORS preflight, which we never grant. */
+export declare const CSRF_HEADER = "x-nextpluggable";
+export declare function sessionView(cfg: ResolvedConfig, request: Request): Promise<SessionView>;
+export declare function createHandler(getConfig: () => ResolvedConfig, hooks?: HandlerHooks): (request: Request) => Promise<Response>;

package/dist/api/handler.js

@@ -0,0 +1,188 @@
+import { addSource, changePlugin, installPlugin, refreshAllSources, removeSource, uninstallPlugin, updatePlugin } from '../core/installer.js';
+import { handlePluginApi } from '../core/runtime.js';
+import { getInstalledPlugins } from '../core/state.js';
+import { getFile, getInstalls } from '../core/store.js';
+import { HttpError, jsonResponse } from '../errors.js';
+import { warnOnce } from '../globals.js';
+import { buildDashboardState } from '../views.js';
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/** Header every dashboard/plugin write must carry. Browsers will not send it cross-site without a CORS preflight, which we never grant. */
+export const CSRF_HEADER = 'x-nextpluggable';
+const hostOf = (value) => {
+    if (!value)
+        return null;
+    try {
+        return new URL(value.includes('://') ? value : `http://${value}`).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * A browser states where a write came from in its Origin header. It must be this site: the host
+ * the request was addressed to, the host a proxy says it forwarded, or the site's configured
+ * public address (for proxies that rewrite the host and forward nothing).
+ */
+function sameOrigin(request, cfg) {
+    const origin = request.headers.get('origin');
+    if (!origin)
+        return true; // non-browser clients; the custom header check still applies
+    const from = hostOf(origin);
+    if (!from)
+        return false;
+    const here = [request.headers.get('x-forwarded-host')?.split(',')[0]?.trim(), request.headers.get('host'), new URL(request.url).host, cfg.siteUrl].map(hostOf);
+    if (here.includes(from))
+        return true;
+    warnOnce(`origin:${from}`, `Blocked a write from ${origin}: it does not match this site (addressed to ${request.headers.get('host') ?? 'unknown'}, forwarded host ${request.headers.get('x-forwarded-host') ?? 'none'}, configured address ${cfg.siteUrl}). If the site sits behind a proxy, set NEXT_PUBLIC_SITE_URL (or siteUrl) to its public address.`);
+    return false;
+}
+/** Look a plugin up by an id that came from a URL, ignoring inherited object properties. */
+const own = (map, key) => (Object.hasOwn(map, key) ? map[key] : undefined);
+const csrfOk = (request, cfg) => request.headers.get(CSRF_HEADER) === '1' && sameOrigin(request, cfg);
+async function readBody(request) {
+    const text = await request.text();
+    if (text.length > 200_000)
+        throw new HttpError(413, 'That request is too large.');
+    if (!text)
+        return {};
+    try {
+        const body = JSON.parse(text);
+        return typeof body === 'object' && body !== null && !Array.isArray(body) ? body : {};
+    }
+    catch {
+        throw new HttpError(400, 'Invalid request.');
+    }
+}
+export async function sessionView(cfg, request) {
+    let user = null;
+    try {
+        user = await cfg.auth.getUser(request, { secret: cfg.secret });
+    }
+    catch (e) {
+        console.error('[nextpluggable] auth.getUser failed:', e);
+    }
+    return { user, mode: cfg.auth.kind, configured: cfg.auth.configured, loginUrl: cfg.auth.loginUrl };
+}
+const ASSET_TYPES = {
+    'client.js': { kind: 'client', type: 'text/javascript; charset=utf-8' },
+    'style.css': { kind: 'style', type: 'text/css; charset=utf-8' },
+};
+async function serveAsset(cfg, pluginId, hash, name) {
+    const asset = ASSET_TYPES[name];
+    if (!asset || !/^[0-9a-f]{16}$/.test(hash))
+        return jsonResponse({ error: 'Not found.' }, 404);
+    const install = own(await getInstalledPlugins(cfg), pluginId) ?? own(await getInstalls(cfg.storage), pluginId);
+    // The previous version's files stay available so pages cached before an update still load.
+    const file = [install?.files[asset.kind], install?.previousFiles?.[asset.kind]].find((f) => f?.sha256.startsWith(hash));
+    const content = file ? await getFile(cfg.storage, pluginId, asset.kind, file.sha256) : null;
+    if (content === null)
+        return jsonResponse({ error: 'Not found.' }, 404);
+    const body = asset.kind === 'client'
+        ? // One artifact, two consumers: the server evaluates the module body directly; browsers get it
+            // wrapped in a registration call, so no eval (and no `unsafe-eval` CSP) is needed client-side.
+            `(self.__NP_Q__=self.__NP_Q__||[]).push([${JSON.stringify(`${pluginId}@${hash}`)},function(require,module,exports){${content}\n}]);`
+        : content;
+    return new Response(body, {
+        headers: {
+            'content-type': asset.type,
+            'cache-control': 'public, max-age=31536000, immutable',
+            'x-content-type-options': 'nosniff',
+        },
+    });
+}
+export function createHandler(getConfig, hooks = {}) {
+    async function route(request) {
+        const cfg = getConfig();
+        const pathname = new URL(request.url).pathname;
+        const at = pathname.indexOf(cfg.apiPath);
+        const sub = at === -1 ? pathname : pathname.slice(at + cfg.apiPath.length);
+        const seg = sub.split('/').filter(Boolean).map((s) => decodeURIComponent(s));
+        const method = request.method.toUpperCase();
+        const env = { secret: cfg.secret };
+        // ---- public: plugin assets
+        if (seg[0] === 'assets' && seg.length === 4 && (method === 'GET' || method === 'HEAD'))
+            return serveAsset(cfg, seg[1], seg[2], seg[3]);
+        // ---- public: plugin APIs
+        if (seg[0] === 'p' && seg[1]) {
+            const install = own(await getInstalledPlugins(cfg), seg[1]);
+            if (!install || !install.enabled)
+                return jsonResponse({ error: 'Not found.' }, 404);
+            // A plugin only sees the dashboard user when the request provably came from this site's own pages.
+            const admin = !MUTATING.has(method) || csrfOk(request, cfg) ? await cfg.auth.getUser(request, env).catch(() => null) : null;
+            const res = await handlePluginApi(cfg, install, request, `/${seg.slice(2).join('/')}`, admin);
+            if (MUTATING.has(method) && admin)
+                await hooks.onSiteChange?.();
+            return res;
+        }
+        // ---- session
+        if (seg[0] === 'session' && method === 'GET')
+            return jsonResponse(await sessionView(cfg, request));
+        if (MUTATING.has(method) && !csrfOk(request, cfg))
+            throw new HttpError(403, 'This request was blocked for security reasons. Reload the page and try again.');
+        if (seg[0] === 'login' && method === 'POST') {
+            if (!cfg.auth.login)
+                throw new HttpError(404, 'This site signs in a different way.');
+            return cfg.auth.login(request, env);
+        }
+        if (seg[0] === 'logout' && method === 'POST')
+            return cfg.auth.logout ? cfg.auth.logout(request, env) : jsonResponse({ ok: true });
+        // ---- dashboard (signed-in only)
+        if (seg[0] !== 'admin')
+            throw new HttpError(404, 'Not found.');
+        const user = await cfg.auth.getUser(request, env);
+        if (!user)
+            throw new HttpError(401, 'Please sign in again.');
+        const state = async (extra) => jsonResponse({ ...(await buildDashboardState(cfg)), ...extra });
+        const changed = async (extra) => {
+            await hooks.onSiteChange?.();
+            return state(extra);
+        };
+        if (seg[1] === 'state' && method === 'GET')
+            return state();
+        if (seg[1] === 'refresh' && method === 'POST')
+            return state({ failures: await refreshAllSources(cfg) });
+        if (seg[1] === 'sources') {
+            if (method === 'POST' && seg.length === 2) {
+                const source = await addSource(cfg, await readBody(request));
+                return state({ added: source.id });
+            }
+            if (method === 'DELETE' && seg[2]) {
+                await removeSource(cfg, seg[2]);
+                return state();
+            }
+        }
+        if (seg[1] === 'install' && method === 'POST') {
+            const record = await installPlugin(cfg, await readBody(request));
+            return changed({ installed: record.id });
+        }
+        if (seg[1] === 'plugins' && seg[2]) {
+            const id = seg[2];
+            if (seg[3] === 'update' && method === 'POST') {
+                await updatePlugin(cfg, id);
+                return changed();
+            }
+            if (seg.length === 3 && method === 'PATCH') {
+                await changePlugin(cfg, id, await readBody(request));
+                return changed();
+            }
+            if (seg.length === 3 && method === 'DELETE') {
+                const body = await readBody(request);
+                await uninstallPlugin(cfg, id, { deleteData: body.deleteData === true });
+                return changed();
+            }
+        }
+        throw new HttpError(404, 'Not found.');
+    }
+    return async function handle(request) {
+        try {
+            return await route(request);
+        }
+        catch (e) {
+            if (e instanceof HttpError)
+                return jsonResponse({ error: e.message, ...(e.fields ? { fields: e.fields } : {}) }, e.status);
+            console.error('[nextpluggable] Unexpected error:', e);
+            const message = e instanceof Error && e.message.startsWith('[nextpluggable]') ? e.message.replace('[nextpluggable] ', '') : 'Something went wrong on the server. Please try again.';
+            return jsonResponse({ error: message }, 500);
+        }
+    };
+}

package/dist/auth/custom.d.ts

@@ -0,0 +1,13 @@
+import type { AdminUser, AuthAdapter } from './types.js';
+export interface CustomAuthOptions {
+    /**
+     * Return the signed-in administrator for this request, or null. Called for the
+     * dashboard page and for every dashboard API request, with the visitor's
+     * cookies and headers on `request`.
+     */
+    getUser: (request: Request) => Promise<AdminUser | null> | AdminUser | null;
+    /** Where to send people who are not signed in, e.g. `/login`. */
+    loginUrl?: string;
+}
+/** Use the site's existing login system (Auth.js, Clerk, Supabase, your own) to protect the dashboard. */
+export declare function customAuth(options: CustomAuthOptions): AuthAdapter;

package/dist/auth/custom.js

@@ -0,0 +1,12 @@
+/** Use the site's existing login system (Auth.js, Clerk, Supabase, your own) to protect the dashboard. */
+export function customAuth(options) {
+    return {
+        kind: 'custom',
+        configured: true,
+        loginUrl: options.loginUrl,
+        async getUser(request) {
+            const user = await options.getUser(request);
+            return user && typeof user.id === 'string' ? { id: user.id, name: user.name } : null;
+        },
+    };
+}

package/dist/auth/password.d.ts

@@ -0,0 +1,10 @@
+import type { AuthAdapter } from './types.js';
+export interface PasswordAuthOptions {
+    /** The dashboard password. Default: the `NEXTPLUGGABLE_PASSWORD` environment variable. */
+    password?: string;
+    /** How long a sign-in lasts. Default 7 days. */
+    sessionDays?: number;
+    cookieName?: string;
+}
+/** One shared password for the dashboard, with a signed, http-only session cookie. */
+export declare function passwordAuth(options?: PasswordAuthOptions): AuthAdapter;

package/dist/auth/password.js

@@ -0,0 +1,66 @@
+import { hmac, safeEqual, signToken, verifyToken } from '../crypto.js';
+import { jsonResponse } from '../errors.js';
+import { globals } from '../globals.js';
+const WINDOW_MS = 10 * 60_000;
+const MAX_ATTEMPTS = 8;
+function clientAddress(request) {
+    return request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || request.headers.get('x-real-ip') || 'unknown';
+}
+function readCookie(request, name) {
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const eq = part.indexOf('=');
+        if (eq !== -1 && part.slice(0, eq).trim() === name)
+            return decodeURIComponent(part.slice(eq + 1).trim());
+    }
+    return undefined;
+}
+function isHttps(request) {
+    const proto = request.headers.get('x-forwarded-proto')?.split(',')[0]?.trim();
+    return proto ? proto === 'https' : new URL(request.url).protocol === 'https:';
+}
+/** One shared password for the dashboard, with a signed, http-only session cookie. */
+export function passwordAuth(options = {}) {
+    const cookieName = options.cookieName ?? 'np_session';
+    const days = options.sessionDays ?? 7;
+    const password = () => options.password ?? process.env.NEXTPLUGGABLE_PASSWORD ?? '';
+    // Sessions carry a fingerprint of the password, so changing it signs everyone out.
+    const fingerprint = (secret) => hmac(secret, `pw:${password()}`).slice(0, 16);
+    const cookie = (request, value, maxAge) => `${cookieName}=${encodeURIComponent(value)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${isHttps(request) ? '; Secure' : ''}`;
+    return {
+        kind: 'password',
+        get configured() {
+            return password().length > 0;
+        },
+        async getUser(request, env) {
+            if (!password())
+                return null;
+            const session = verifyToken(env.secret, readCookie(request, cookieName));
+            return session && session.fp === fingerprint(env.secret) ? { id: 'admin', name: 'Site owner' } : null;
+        },
+        async login(request, env) {
+            if (!password())
+                return jsonResponse({ error: 'No dashboard password has been set up yet.' }, 503);
+            const attempts = globals().loginAttempts;
+            const who = clientAddress(request);
+            const now = Date.now();
+            const recent = (attempts.get(who) ?? []).filter((t) => now - t < WINDOW_MS);
+            if (recent.length >= MAX_ATTEMPTS) {
+                attempts.set(who, recent);
+                return jsonResponse({ error: 'Too many attempts. Please wait a few minutes and try again.' }, 429);
+            }
+            const body = (await request.json().catch(() => null));
+            const given = typeof body?.password === 'string' ? body.password : '';
+            if (!given || !safeEqual(given, password())) {
+                recent.push(now);
+                attempts.set(who, recent);
+                return jsonResponse({ error: 'That password is not right.' }, 401);
+            }
+            attempts.delete(who);
+            const token = signToken(env.secret, { exp: now + days * 86_400_000, fp: fingerprint(env.secret) });
+            return jsonResponse({ user: { id: 'admin', name: 'Site owner' } }, 200, { 'set-cookie': cookie(request, token, days * 86_400) });
+        },
+        async logout(request) {
+            return jsonResponse({ ok: true }, 200, { 'set-cookie': cookie(request, '', 0) });
+        },
+    };
+}

package/dist/auth/types.d.ts

@@ -0,0 +1,23 @@
+export interface AdminUser {
+    id: string;
+    name?: string;
+}
+export interface AuthEnv {
+    /** The site secret, for signing sessions. */
+    secret: string;
+}
+/**
+ * Decides who may use the dashboard. Use `passwordAuth()` for a single shared
+ * password, or `customAuth()` to defer to the site's own login (Auth.js, Clerk, …).
+ */
+export interface AuthAdapter {
+    kind: 'password' | 'custom';
+    /** False when the adapter cannot work yet (e.g. no password set); the dashboard then shows setup steps. */
+    configured: boolean;
+    getUser(request: Request, env: AuthEnv): Promise<AdminUser | null>;
+    /** Password adapters: handle a sign-in attempt. */
+    login?(request: Request, env: AuthEnv): Promise<Response>;
+    logout?(request: Request, env: AuthEnv): Promise<Response>;
+    /** Custom adapters: where to send someone who is not signed in. */
+    loginUrl?: string;
+}

package/dist/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+export interface InitResult {
+    created: string[];
+    skipped: string[];
+    notes: string[];
+    /** Set when a dashboard password was generated. */
+    password?: string;
+}
+export declare function init(projectDir: string): Promise<InitResult>;
+export declare function main(): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,119 @@
+/**
+ * `npx nextpluggable init` — wire NextPluggable into an existing Next.js (App Router) site.
+ * Creates four small files and never overwrites anything that already exists.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const importPath = (fromFile, toFile) => {
+    const rel = path.relative(path.dirname(fromFile), toFile).split(path.sep).join('/').replace(/\.(t|j)sx?$/, '');
+    return rel.startsWith('.') ? rel : `./${rel}`;
+};
+export async function init(projectDir) {
+    const root = path.resolve(projectDir);
+    const result = { created: [], skipped: [], notes: [] };
+    const appDir = ['app', 'src/app'].map((d) => path.join(root, d)).find((d) => existsSync(d));
+    if (!appDir)
+        throw new Error('No "app" directory found. NextPluggable needs a Next.js project that uses the App Router (run this in the project root).');
+    const ts = existsSync(path.join(root, 'tsconfig.json'));
+    const x = ts ? 'ts' : 'js';
+    const libFile = path.join(path.dirname(appDir), 'lib', `nextpluggable.${x}`);
+    const rel = (file) => path.relative(root, file).split(path.sep).join('/');
+    async function create(file, content) {
+        if (existsSync(file))
+            return void result.skipped.push(rel(file));
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, content);
+        result.created.push(rel(file));
+    }
+    await create(libFile, `import { createNextPluggable } from 'nextpluggable';
+
+// Sign-in: one password, read from NEXTPLUGGABLE_PASSWORD. To use your site's own
+// login instead, pass \`auth: customAuth({ getUser })\`.
+// Data: a .nextpluggable folder next to your project. On serverless hosts
+// (Vercel, Netlify) pass a database instead, e.g. \`storage: upstashStorage()\`.
+export const np = createNextPluggable({
+  siteName: 'My site',
+});
+`);
+    const apiRoute = path.join(appDir, 'api', 'nextpluggable', '[...np]', `route.${x}`);
+    await create(apiRoute, `import { np } from '${importPath(apiRoute, libFile)}';\n\nexport const { GET, POST, PUT, PATCH, DELETE } = np.handlers;\n`);
+    const dashboard = path.join(appDir, 'admin', 'plugins', '[[...np]]', `page.${x}x`);
+    await create(dashboard, `import { np } from '${importPath(dashboard, libFile)}';\n\nexport const metadata = np.dashboardMetadata;\nexport default np.DashboardPage;\n`);
+    // A root catch-all is where plugin pages are served. If the site already has one, it must be merged by hand.
+    const existingCatchAll = (await readdir(appDir, { withFileTypes: true })).find((e) => e.isDirectory() && /^\[\[?\.\.\..+\]\]?$/.test(e.name));
+    if (existingCatchAll) {
+        result.notes.push(`Your site already has a catch-all route (${rel(path.join(appDir, existingCatchAll.name))}). To serve plugin pages from it, render \`<np.PluginPage params={params} />\` there when your own lookup finds nothing, or ask \`await np.hasPluginPage(pathname)\` first if that route never returns a 404.`);
+    }
+    else {
+        const catchAll = path.join(appDir, '[...slug]', `page.${x}x`);
+        await create(catchAll, `import { np } from '${importPath(catchAll, libFile)}';
+
+// Addresses your own routes don't handle land here. Installed plugins answer
+// for the pages they add; everything else gets your normal 404 page.
+export const generateMetadata = np.generatePluginMetadata;
+export default np.PluginPage;
+
+// Faster and cheaper: uncomment the next two lines to cache plugin pages like
+// static pages. The dashboard refreshes the cache whenever a plugin changes.
+// Only do this if nothing in your root layout reads cookies() or headers() on
+// the server: with caching on, such a layout makes these pages fail with a
+// 500 error in production builds (it will not show up in \`next dev\`).
+// export const generateStaticParams = async () => [];
+// export const revalidate = 3600;
+`);
+    }
+    if (['tsx', 'jsx', 'js'].some((ext) => existsSync(path.join(appDir, `loading.${ext}`))))
+        result.notes.push('Your app has a root loading file. While plugin pages are uncached (the default), it makes addresses that do not exist return "200 OK" with a noindex tag instead of a 404. To get real 404s, switch on caching in the catch-all route (see the comment in that file) or move the loading file into a route group.');
+    // Secrets for local development.
+    const envFile = path.join(root, '.env.local');
+    const env = existsSync(envFile) ? await readFile(envFile, 'utf8') : '';
+    const additions = [];
+    if (!/^NEXTPLUGGABLE_PASSWORD=/m.test(env)) {
+        result.password = randomBytes(9).toString('base64url');
+        additions.push(`NEXTPLUGGABLE_PASSWORD=${result.password}`);
+    }
+    if (!/^NEXTPLUGGABLE_SECRET=/m.test(env))
+        additions.push(`NEXTPLUGGABLE_SECRET=${randomBytes(32).toString('base64url')}`);
+    if (additions.length) {
+        await appendFile(envFile, `${env && !env.endsWith('\n') ? '\n' : ''}\n# NextPluggable (plugin dashboard)\n${additions.join('\n')}\n`);
+        result.created.push('.env.local (added NextPluggable settings)');
+    }
+    const gitignore = path.join(root, '.gitignore');
+    if (existsSync(gitignore)) {
+        const current = await readFile(gitignore, 'utf8');
+        if (!/^\/?\.nextpluggable\/?$/m.test(current))
+            await appendFile(gitignore, `${current.endsWith('\n') ? '' : '\n'}\n# NextPluggable local data\n.nextpluggable/\n`);
+        if (!/^\.env(\.local|\*|\.\*)?$/m.test(current))
+            result.notes.push('Make sure .env.local is not committed: it now holds your dashboard password.');
+    }
+    return result;
+}
+const HELP = `nextpluggable — WordPress-style plugins for Next.js
+
+Usage:
+  npx nextpluggable init [dir]    Add the dashboard, API route and plugin page route to a Next.js site
+`;
+export async function main() {
+    const [command, dir] = process.argv.slice(2);
+    if (command !== 'init') {
+        console.log(HELP);
+        return command && command !== 'help' && command !== '--help' ? 1 : 0;
+    }
+    const result = await init(dir ?? '.');
+    for (const f of result.created)
+        console.log(`  created  ${f}`);
+    for (const f of result.skipped)
+        console.log(`  kept     ${f} (already exists)`);
+    console.log(`
+Next steps
+  1. Start your site and open /admin/plugins${result.password ? `\n     Dashboard password: ${result.password}  (saved in .env.local)` : ''}
+  2. Optional: add <np.Slot name="header.actions" />, <np.Slot name="footer" /> and
+     <np.Slot name="body.end" /> to your root layout so plugins can add buttons and widgets there.
+  3. Before going live, set NEXTPLUGGABLE_PASSWORD and NEXTPLUGGABLE_SECRET on your host,
+     and choose a storage adapter if the host has no persistent disk.`);
+    for (const note of result.notes)
+        console.log(`\nNote: ${note}`);
+    return 0;
+}

package/dist/client/host-runtime.d.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import type { HostRuntime, PluginApi, PluginInfo } from '@nextpluggable/plugin';
+export interface PluginRuntimeValue {
+    info: PluginInfo;
+    config: Record<string, unknown>;
+}
+export declare const PluginRuntimeContext: React.Context<PluginRuntimeValue | null>;
+export declare function createPluginApi(apiBase: string): PluginApi;
+export declare const hostRuntime: HostRuntime;

package/dist/client/host-runtime.js

@@ -0,0 +1,71 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The host's implementation of `@nextpluggable/plugin`. Plugin bundles keep that
+ * module external; when they `require` it they receive this object, so every
+ * plugin shares the site's React, router and context.
+ */
+import NextLink from 'next/link';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import * as React from 'react';
+export const PluginRuntimeContext = React.createContext(null);
+function useRuntime() {
+    const value = React.useContext(PluginRuntimeContext);
+    if (!value)
+        throw new Error('Plugin hooks can only be used inside a plugin component.');
+    return value;
+}
+export function createPluginApi(apiBase) {
+    return (path, init = {}) => {
+        const { json, headers, ...rest } = init;
+        const h = new Headers(headers);
+        h.set('x-nextpluggable', '1');
+        if (json !== undefined)
+            h.set('content-type', 'application/json');
+        return fetch(`${apiBase}${path.startsWith('/') ? path : `/${path}`}`, {
+            credentials: 'same-origin',
+            ...rest,
+            headers: h,
+            body: json !== undefined ? JSON.stringify(json) : rest.body,
+        });
+    };
+}
+const subscribeToNothing = () => () => { };
+export const hostRuntime = {
+    usePluginConfig() {
+        return useRuntime().config;
+    },
+    usePlugin() {
+        return useRuntime().info;
+    },
+    usePluginApi() {
+        const { apiBase } = useRuntime().info;
+        return React.useMemo(() => createPluginApi(apiBase), [apiBase]);
+    },
+    useNavigation() {
+        const router = useRouter();
+        const pathname = usePathname();
+        return React.useMemo(() => ({
+            pathname,
+            push: (href) => router.push(href),
+            replace: (href) => router.replace(href),
+            back: () => router.back(),
+        }), [router, pathname]);
+    },
+    useQuery() {
+        // The query string must never reach server-rendered HTML: plugin pages may be cached and
+        // served to every visitor, and a query can carry private values. So it is not read on the
+        // server at all, stays empty while the browser hydrates (to match that HTML), and becomes
+        // available on the first update after.
+        // eslint-disable-next-line react-hooks/rules-of-hooks -- the branch is fixed per environment
+        const live = typeof window === 'undefined' ? null : useSearchParams();
+        const hydrated = React.useSyncExternalStore(subscribeToNothing, () => true, () => false);
+        const search = hydrated && live ? live.toString() : '';
+        return React.useMemo(() => new URLSearchParams(search), [search]);
+    },
+    Link(props) {
+        return _jsx(NextLink, { ...props });
+    },
+};
+// Also reachable through the published SDK module, in case a plugin bundled it by mistake.
+globalThis[Symbol.for('nextpluggable.host-runtime')] = hostRuntime;

package/dist/client/island.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Renders a component from a plugin bundle that was not part of this site's build.
+ *
+ * Server (SSR pass): the bundle's source was placed in process memory by the
+ * server component that rendered us; it is evaluated here with THIS module
+ * graph's React, so the plugin renders into the same tree as the rest of the page.
+ *
+ * Browser: the same bundle arrives as a <script>, registers itself, and is
+ * given the browser's React. `use()` suspends until it has, and React keeps the
+ * server-rendered HTML in place and hydrates it once the module is ready.
+ */
+import * as React from 'react';
+import * as jsxRuntime from 'react/jsx-runtime';
+import type { PluginInfo } from '@nextpluggable/plugin';
+export interface PluginIslandProps {
+    moduleKey: string;
+    src: string;
+    /** Name of the export to render. */
+    component: string;
+    info: PluginInfo;
+    config: Record<string, unknown>;
+    props?: Record<string, unknown>;
+    /** Shown if the plugin crashes. Slots default to nothing so a broken widget never breaks the page around it. */
+    errorFallback?: React.ReactNode;
+    /** Shown while the bundle loads on client-side navigation. */
+    loadingFallback?: React.ReactNode;
+}
+export declare function PluginIsland(p: PluginIslandProps): jsxRuntime.JSX.Element;