@plurid/plurid-react-server 0.0.0-15 → 0.0.0-17

package/README.md

@@ -5,7 +5,7 @@
     <a target="_blank" href="https://www.npmjs.com/package/@plurid/plurid-react-server">
         <img src="https://img.shields.io/npm/v/@plurid/plurid-react-server.svg?logo=npm&colorB=1380C3&style=for-the-badge" alt="Version">
     </a>
-    <a target="_blank" href="https://github.com/plurid/plurid-react-server/blob/master/LICENSE">
+    <a target="_blank" href="https://github.com/plurid/plurid/blob/master/LICENSE">
         <img src="https://img.shields.io/badge/license-DEL-blue.svg?colorB=1380C3&style=for-the-badge" alt="License: DEL">
     </a>
 </p>
@@ -17,9 +17,73 @@
 </h1>
 
 
-Server side rendering using `React` of [plurid'](https://github.com/plurid/plurid) to view and explore information as a 3D structure.
+Server-side rendering for [plurid'](https://github.com/plurid/plurid) — render a plurid 3D space to HTML on
+the server (faster first paint, crawlable markup), with an optional **static "stills"** pipeline for
+pre-rendering routes ahead of time.
 
 
-<p align="center">
-    <img src="https://raw.githubusercontent.com/plurid/plurid/master/about/demo/plurid-com-example.png" height="600px">
-</p>
+## Install
+
+`@plurid/plurid-react-server` is normally scaffolded by
+[`@plurid/generate-plurid-app`](https://github.com/plurid/plurid/tree/master/packages/plurid-utilities/generate-plurid-app)
+(server templates). The two runnable references are
+[`fixtures/plurid-react-typescript-server`](https://github.com/plurid/plurid/tree/master/fixtures) and its
+JavaScript twin.
+
+``` bash
+npm install @plurid/plurid-react-server
+```
+
+
+## Server-side rendering
+
+`PluridServer` is an Express server: it matches the request route, computes the plurid metastate via
+`@plurid/plurid-react`'s `serverComputeMetastate`, renders the React tree to HTML (styled-components +
+`react-helmet-async`), injects the metastate, and responds. Construct it with your routes / planes / helmet
+/ services and `start(port)` — see the server fixtures for a complete setup.
+
+``` ts
+import PluridServer from '@plurid/plurid-react-server';
+
+const server = new PluridServer({ routes, planes, preserves, helmet, /* … */ });
+server.start(3000);
+```
+
+
+## Static stills (optional, Puppeteer)
+
+A **still** is a route pre-rendered to static HTML ahead of time. When a still exists for a request, the
+server sends it directly and skips on-the-fly rendering. Stills are entirely opt-in.
+
+> **Puppeteer is an optional peer dependency** — only stills *generation* needs it; SSR does not. Install it
+> where you generate stills:
+> ``` bash
+> npm install puppeteer
+> ```
+
+**Generating** stills (`PluridStillsGenerator`) — run it after building your server bundle:
+
+``` ts
+import { PluridStillsGenerator } from '@plurid/plurid-react-server';
+
+// reads routes from the BUILT server (default ./build/server.js), spins it up on a free port,
+// drives Puppeteer over each static (non-parameterized) route, and writes:
+//   build/stills/<uuid>.json   (one per route)  +  build/stills/metadata.json  (the route → file index)
+await new PluridStillsGenerator({ server: './build/server.js', build: './build/' }).initialize();
+```
+
+The order matters: **build the server first**, then run the generator (it `require()`s the built bundle and
+fails with a clear message if it's missing). Parameterized routes (`/x/:id`) and `stiller.ignore` routes are
+skipped. One headless browser is reused across all routes; a navigation failure aborts the run with the
+underlying reason rather than writing partial output.
+
+**Serving** stills — automatic: on startup `PluridServer` loads `build/stills/metadata.json` (the
+`stillsDirectory` under `buildDirectory`) and serves a matching still before falling back to live SSR. Tune
+generation via the server's `stiller` option (`waitUntil`, `timeout`, `ignore`).
+
+
+## Documentation
+
+Full engine docs: the repo [`README`](https://github.com/plurid/plurid),
+[`GETTING_STARTED`](https://github.com/plurid/plurid/blob/master/GETTING_STARTED.md), and
+[`CONTROL_SURFACE`](https://github.com/plurid/plurid/blob/master/docs/CONTROL_SURFACE.md).

package/distribution/index.d.mts

@@ -0,0 +1,296 @@
+import * as http from 'http';
+import { Server } from 'http';
+import express from 'express';
+import { PluridPreserve, IsoMatcherRouteResult, PluridRoute, PluridRoutePlane, PluridRouterProperties } from '@plurid/plurid-data';
+import { PluridReactComponent } from '@plurid/plurid-react';
+import { Helmet } from 'react-helmet-async';
+
+type PluridServerMiddleware = (request: express.Request, response: express.Response, next: express.NextFunction) => void;
+type ServerRequest = express.Request & {
+    requestID: string;
+    requestTime: number;
+};
+type DebugLevels = 'none' | 'error' | 'warn' | 'info';
+interface PluridServerOptions {
+    /** To be used for logging. Default `Plurid Server` */
+    serverName: string;
+    /**
+     * The hostname of the server exposed to the internet, e.g. `example.com`,
+     * to be used in plurid plane links.
+     */
+    hostname: string;
+    /**
+     * To log or not to log to the console.
+     */
+    quiet: boolean;
+    /**
+     * Debug levels.
+     *
+     * Production default: `error`.
+     * Development default: `info` and above.
+     */
+    debug: DebugLevels;
+    /**
+     * Use `gzip` compression for the response. Default `true`.
+     */
+    compression: boolean;
+    /**
+     * Open in browser at start.
+     */
+    open: boolean;
+    /**
+     * Name of the directory where the files (server and client) are bundled.
+     */
+    buildDirectory: string;
+    /**
+     * Name of the directory where the assets files are bundled.
+     */
+    assetsDirectory: string;
+    /**
+     * Directory of static assets (favicon, og-image, manifest, robots) served at
+     * the URL root `/`. Empty string (the default) resolves to
+     * `<buildDirectory>/public`; the mount is skipped if the directory does not
+     * exist, so apps without a public directory are unaffected. The framework
+     * points this at `source/public` during `plurid dev`.
+     */
+    publicDirectory: string;
+    /**
+     * Default: `/gateway`.
+     */
+    gatewayEndpoint: string;
+    /**
+     * Provide a `max-age` in milliseconds for http caching of the static serves.
+     * This can also be a string accepted by the `ms` module.
+     *
+     * Default: 0.
+     */
+    staticCache: number | string;
+    /**
+     * Routes to be ignored when serving the application (`GET`).
+     */
+    ignore: string[];
+    /**
+     * Name of the directory where the stills are gathered.
+     */
+    stillsDirectory: string;
+    stiller: PluridStillerOptions;
+    /**
+     * Install `SIGINT`/`SIGTERM` handlers that stop the server and call `process.exit`.
+     * Defaults to `true` (convenient for the CLI). Set to `false` when EMBEDDING the server
+     * in a host process you do not want it to terminate; then manage lifecycle via `stop()`.
+     */
+    attachSignalHandlers: boolean;
+}
+type PluridServerPartialOptions = Partial<PluridServerOptions>;
+interface PluridServerService<P = any, PP = any> {
+    name: string;
+    Provider: P;
+    properties?: PP;
+}
+interface PluridServerConfiguration {
+    routes: PluridRoute<PluridReactComponent>[];
+    planes?: PluridRoutePlane<PluridReactComponent>[];
+    preserves: PluridPreserveReact[];
+    helmet: Helmet;
+    styles?: string[];
+    middleware?: PluridServerMiddleware[];
+    exterior?: PluridReactComponent;
+    shell?: PluridReactComponent;
+    routerProperties?: Partial<PluridRouterProperties<PluridReactComponent>>;
+    /**
+     * Replace the internal plurid plane with a custom implementation.
+     */
+    customPlane?: PluridReactComponent;
+    /**
+     * Services to be handled by the server.
+     *
+     * Supported: `GraphQL`, `Redux`, `Stripe`.
+     */
+    services?: PluridServerService[];
+    options?: PluridServerPartialOptions;
+    template?: PluridServerTemplateConfiguration;
+    usePTTP?: boolean;
+    pttpHandler?: PTTPHandler;
+    elementqlEndpoint?: string;
+}
+type PTTPHandler = (path: string) => Promise<boolean>;
+interface PluridServerTemplateConfiguration {
+    htmlLanguage?: string;
+    htmlAttributes?: Record<string, string>;
+    defaultStyle?: string;
+    headScripts?: string[];
+    bodyScripts?: string[];
+    /**
+     * The JavaScript vendor filepath to inject in the HTML template.
+     * Default `'/vendor.js'`.
+     *
+     * A CDN link can be used for better caching.
+     */
+    vendorScriptSource?: string;
+    /**
+     * The JavaScript filename to inject in the HTML template.
+     */
+    mainScriptSource?: string;
+    bodyAttributes?: Record<string, string>;
+    /**
+     * The ID of the root element in the HTML template.
+     */
+    root?: string;
+    /**
+     * Global variable name to be attached to window on the server-side
+     * to preload plurid metastate.
+     *
+     * Default: `__PRELOADED_PLURID_METASTATE__`
+     */
+    defaultPreloadedPluridMetastate?: string;
+    minify?: boolean;
+    /**
+     * Favicon links injected into `<head>`. A bare string is the primary icon
+     * (`rel="icon"`); the object expands to icon / apple-touch-icon / sized /
+     * mask-icon links plus a `theme-color` meta. Paths resolve against the served
+     * public directory (see `PluridServerOptions.publicDirectory`).
+     */
+    favicon?: string | {
+        icon?: string;
+        apple?: string;
+        sizes?: Record<string, string>;
+        maskIcon?: string;
+        themeColor?: string;
+    };
+    /**
+     * Web app manifest href, injected as `<link rel="manifest">`.
+     */
+    manifest?: string;
+    /**
+     * Static `<head>` metadata injected AHEAD of the react-helmet-async output,
+     * so per-route `<Helmet>` tags still override these defaults.
+     */
+    head?: {
+        title?: string;
+        description?: string;
+        meta?: Array<{
+            name?: string;
+            property?: string;
+            content: string;
+        }>;
+        links?: Array<{
+            rel: string;
+            href: string;
+        }>;
+    };
+    /**
+     * Override the built-in 500 error page HTML (sent on a render failure).
+     */
+    errorHtml?: string;
+}
+interface PluridStillerOptions {
+    /**
+     * Recommended: `'networkidle0'` | `'networkidle2'` | `'load'`.
+     *
+     * Default: `'networkidle0'`.
+     */
+    waitUntil: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+    /**
+     * Maximum navigation time in milliseconds, pass 0 to disable timeout.
+     *
+     * Default: 30000.
+     */
+    timeout: number;
+    /**
+     * Routes to be ignored by the stilling process.
+     */
+    ignore: string[];
+}
+type PluridPreserveReact = PluridPreserve<IsoMatcherRouteResult<PluridReactComponent<any>> | undefined, express.Request, express.Response>;
+interface PluridLiveServerOptions {
+    server: string;
+}
+
+interface StillsGeneratorOptions {
+    server: string;
+    build: string;
+}
+
+declare class PluridServer {
+    private routes;
+    private planes;
+    private preserves;
+    private helmet;
+    private styles;
+    private middleware;
+    private exterior;
+    private shell;
+    private routerProperties;
+    private services;
+    private options;
+    private template;
+    usePTTP: boolean;
+    private pttpHandler;
+    private elementqlEndpoint;
+    private serverApplication;
+    private server;
+    private port;
+    private stills;
+    private isoMatcher;
+    constructor(configuration: PluridServerConfiguration);
+    private handleProcessSignal;
+    private signalHandlersAttached;
+    attachSignalHandlers(): void;
+    detachSignalHandlers(): void;
+    static analysis(pluridServer: PluridServer): {
+        routes: PluridRoute<PluridReactComponent, any>[];
+        options: PluridServerOptions;
+    };
+    start(port?: string | number): Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    stop(): void;
+    handle(): {
+        post: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+        patch: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+        put: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+        delete: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+    };
+    instance(): express.Express;
+    private handleEndpoints;
+    private handleGetRequest;
+    private handlePTTPRequest;
+    private ignoreGetRequest;
+    private resolveMatchingPath;
+    private resolvePreserve;
+    private resolvePreserveAfterServe;
+    private handleGateway;
+    private renderApplication;
+    /**
+     * Build the static `<head>` markup from the template config (favicon set,
+     * manifest, default title / meta / links). Returns an empty string when none
+     * are configured, so the head is byte-identical to before for existing apps.
+     */
+    private buildStaticHead;
+    private getContentAndStyles;
+    private computeRequestTime;
+    private handleOptions;
+    private configureServer;
+    private loadMiddleware;
+    private open;
+    private debugAllows;
+}
+
+declare class LiveServer {
+    private options;
+    private expressServer;
+    private httpServer;
+    private sockets;
+    constructor(options?: Partial<PluridLiveServerOptions>);
+    private resolveOptions;
+    private setupExpressServer;
+    private setupHttpServer;
+    start(): never;
+}
+
+declare class StillsGenerator {
+    private options;
+    constructor(options?: Partial<StillsGeneratorOptions>);
+    resolveOptions(options?: Partial<StillsGeneratorOptions>): StillsGeneratorOptions;
+    initialize(): Promise<void>;
+}
+
+export { type DebugLevels, type PTTPHandler, LiveServer as PluridLiveServer, type PluridLiveServerOptions, type PluridPreserveReact, type PluridServerConfiguration, type PluridServerMiddleware, type PluridServerOptions, type PluridServerPartialOptions, type PluridServerService, type PluridServerTemplateConfiguration, type PluridStillerOptions, StillsGenerator as PluridStillsGenerator, type ServerRequest, PluridServer as default };

package/distribution/index.d.ts

@@ -1,6 +1,296 @@
-import PluridServer from './objects/Server';
-import PluridLiveServer from './objects/LiveServer';
-import PluridStillsGenerator from './objects/StillsGenerator';
-export * from './data/interfaces/external';
-export { PluridLiveServer, PluridStillsGenerator, };
-export default PluridServer;
+import * as http from 'http';
+import { Server } from 'http';
+import express from 'express';
+import { PluridPreserve, IsoMatcherRouteResult, PluridRoute, PluridRoutePlane, PluridRouterProperties } from '@plurid/plurid-data';
+import { PluridReactComponent } from '@plurid/plurid-react';
+import { Helmet } from 'react-helmet-async';
+
+type PluridServerMiddleware = (request: express.Request, response: express.Response, next: express.NextFunction) => void;
+type ServerRequest = express.Request & {
+    requestID: string;
+    requestTime: number;
+};
+type DebugLevels = 'none' | 'error' | 'warn' | 'info';
+interface PluridServerOptions {
+    /** To be used for logging. Default `Plurid Server` */
+    serverName: string;
+    /**
+     * The hostname of the server exposed to the internet, e.g. `example.com`,
+     * to be used in plurid plane links.
+     */
+    hostname: string;
+    /**
+     * To log or not to log to the console.
+     */
+    quiet: boolean;
+    /**
+     * Debug levels.
+     *
+     * Production default: `error`.
+     * Development default: `info` and above.
+     */
+    debug: DebugLevels;
+    /**
+     * Use `gzip` compression for the response. Default `true`.
+     */
+    compression: boolean;
+    /**
+     * Open in browser at start.
+     */
+    open: boolean;
+    /**
+     * Name of the directory where the files (server and client) are bundled.
+     */
+    buildDirectory: string;
+    /**
+     * Name of the directory where the assets files are bundled.
+     */
+    assetsDirectory: string;
+    /**
+     * Directory of static assets (favicon, og-image, manifest, robots) served at
+     * the URL root `/`. Empty string (the default) resolves to
+     * `<buildDirectory>/public`; the mount is skipped if the directory does not
+     * exist, so apps without a public directory are unaffected. The framework
+     * points this at `source/public` during `plurid dev`.
+     */
+    publicDirectory: string;
+    /**
+     * Default: `/gateway`.
+     */
+    gatewayEndpoint: string;
+    /**
+     * Provide a `max-age` in milliseconds for http caching of the static serves.
+     * This can also be a string accepted by the `ms` module.
+     *
+     * Default: 0.
+     */
+    staticCache: number | string;
+    /**
+     * Routes to be ignored when serving the application (`GET`).
+     */
+    ignore: string[];
+    /**
+     * Name of the directory where the stills are gathered.
+     */
+    stillsDirectory: string;
+    stiller: PluridStillerOptions;
+    /**
+     * Install `SIGINT`/`SIGTERM` handlers that stop the server and call `process.exit`.
+     * Defaults to `true` (convenient for the CLI). Set to `false` when EMBEDDING the server
+     * in a host process you do not want it to terminate; then manage lifecycle via `stop()`.
+     */
+    attachSignalHandlers: boolean;
+}
+type PluridServerPartialOptions = Partial<PluridServerOptions>;
+interface PluridServerService<P = any, PP = any> {
+    name: string;
+    Provider: P;
+    properties?: PP;
+}
+interface PluridServerConfiguration {
+    routes: PluridRoute<PluridReactComponent>[];
+    planes?: PluridRoutePlane<PluridReactComponent>[];
+    preserves: PluridPreserveReact[];
+    helmet: Helmet;
+    styles?: string[];
+    middleware?: PluridServerMiddleware[];
+    exterior?: PluridReactComponent;
+    shell?: PluridReactComponent;
+    routerProperties?: Partial<PluridRouterProperties<PluridReactComponent>>;
+    /**
+     * Replace the internal plurid plane with a custom implementation.
+     */
+    customPlane?: PluridReactComponent;
+    /**
+     * Services to be handled by the server.
+     *
+     * Supported: `GraphQL`, `Redux`, `Stripe`.
+     */
+    services?: PluridServerService[];
+    options?: PluridServerPartialOptions;
+    template?: PluridServerTemplateConfiguration;
+    usePTTP?: boolean;
+    pttpHandler?: PTTPHandler;
+    elementqlEndpoint?: string;
+}
+type PTTPHandler = (path: string) => Promise<boolean>;
+interface PluridServerTemplateConfiguration {
+    htmlLanguage?: string;
+    htmlAttributes?: Record<string, string>;
+    defaultStyle?: string;
+    headScripts?: string[];
+    bodyScripts?: string[];
+    /**
+     * The JavaScript vendor filepath to inject in the HTML template.
+     * Default `'/vendor.js'`.
+     *
+     * A CDN link can be used for better caching.
+     */
+    vendorScriptSource?: string;
+    /**
+     * The JavaScript filename to inject in the HTML template.
+     */
+    mainScriptSource?: string;
+    bodyAttributes?: Record<string, string>;
+    /**
+     * The ID of the root element in the HTML template.
+     */
+    root?: string;
+    /**
+     * Global variable name to be attached to window on the server-side
+     * to preload plurid metastate.
+     *
+     * Default: `__PRELOADED_PLURID_METASTATE__`
+     */
+    defaultPreloadedPluridMetastate?: string;
+    minify?: boolean;
+    /**
+     * Favicon links injected into `<head>`. A bare string is the primary icon
+     * (`rel="icon"`); the object expands to icon / apple-touch-icon / sized /
+     * mask-icon links plus a `theme-color` meta. Paths resolve against the served
+     * public directory (see `PluridServerOptions.publicDirectory`).
+     */
+    favicon?: string | {
+        icon?: string;
+        apple?: string;
+        sizes?: Record<string, string>;
+        maskIcon?: string;
+        themeColor?: string;
+    };
+    /**
+     * Web app manifest href, injected as `<link rel="manifest">`.
+     */
+    manifest?: string;
+    /**
+     * Static `<head>` metadata injected AHEAD of the react-helmet-async output,
+     * so per-route `<Helmet>` tags still override these defaults.
+     */
+    head?: {
+        title?: string;
+        description?: string;
+        meta?: Array<{
+            name?: string;
+            property?: string;
+            content: string;
+        }>;
+        links?: Array<{
+            rel: string;
+            href: string;
+        }>;
+    };
+    /**
+     * Override the built-in 500 error page HTML (sent on a render failure).
+     */
+    errorHtml?: string;
+}
+interface PluridStillerOptions {
+    /**
+     * Recommended: `'networkidle0'` | `'networkidle2'` | `'load'`.
+     *
+     * Default: `'networkidle0'`.
+     */
+    waitUntil: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+    /**
+     * Maximum navigation time in milliseconds, pass 0 to disable timeout.
+     *
+     * Default: 30000.
+     */
+    timeout: number;
+    /**
+     * Routes to be ignored by the stilling process.
+     */
+    ignore: string[];
+}
+type PluridPreserveReact = PluridPreserve<IsoMatcherRouteResult<PluridReactComponent<any>> | undefined, express.Request, express.Response>;
+interface PluridLiveServerOptions {
+    server: string;
+}
+
+interface StillsGeneratorOptions {
+    server: string;
+    build: string;
+}
+
+declare class PluridServer {
+    private routes;
+    private planes;
+    private preserves;
+    private helmet;
+    private styles;
+    private middleware;
+    private exterior;
+    private shell;
+    private routerProperties;
+    private services;
+    private options;
+    private template;
+    usePTTP: boolean;
+    private pttpHandler;
+    private elementqlEndpoint;
+    private serverApplication;
+    private server;
+    private port;
+    private stills;
+    private isoMatcher;
+    constructor(configuration: PluridServerConfiguration);
+    private handleProcessSignal;
+    private signalHandlersAttached;
+    attachSignalHandlers(): void;
+    detachSignalHandlers(): void;
+    static analysis(pluridServer: PluridServer): {
+        routes: PluridRoute<PluridReactComponent, any>[];
+        options: PluridServerOptions;
+    };
+    start(port?: string | number): Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    stop(): void;
+    handle(): {
+        post: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+        patch: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+        put: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+        delete: (path: string, ...handlers: express.RequestHandler[]) => express.Express;
+    };
+    instance(): express.Express;
+    private handleEndpoints;
+    private handleGetRequest;
+    private handlePTTPRequest;
+    private ignoreGetRequest;
+    private resolveMatchingPath;
+    private resolvePreserve;
+    private resolvePreserveAfterServe;
+    private handleGateway;
+    private renderApplication;
+    /**
+     * Build the static `<head>` markup from the template config (favicon set,
+     * manifest, default title / meta / links). Returns an empty string when none
+     * are configured, so the head is byte-identical to before for existing apps.
+     */
+    private buildStaticHead;
+    private getContentAndStyles;
+    private computeRequestTime;
+    private handleOptions;
+    private configureServer;
+    private loadMiddleware;
+    private open;
+    private debugAllows;
+}
+
+declare class LiveServer {
+    private options;
+    private expressServer;
+    private httpServer;
+    private sockets;
+    constructor(options?: Partial<PluridLiveServerOptions>);
+    private resolveOptions;
+    private setupExpressServer;
+    private setupHttpServer;
+    start(): never;
+}
+
+declare class StillsGenerator {
+    private options;
+    constructor(options?: Partial<StillsGeneratorOptions>);
+    resolveOptions(options?: Partial<StillsGeneratorOptions>): StillsGeneratorOptions;
+    initialize(): Promise<void>;
+}
+
+export { type DebugLevels, type PTTPHandler, LiveServer as PluridLiveServer, type PluridLiveServerOptions, type PluridPreserveReact, type PluridServerConfiguration, type PluridServerMiddleware, type PluridServerOptions, type PluridServerPartialOptions, type PluridServerService, type PluridServerTemplateConfiguration, type PluridStillerOptions, StillsGenerator as PluridStillsGenerator, type ServerRequest, PluridServer as default };