@arcanejs/toolkit 6.0.1 → 7.0.0

package/dist/{toolkit-C_2Y8N9R.d.ts → toolkit-Bglbv3ix.d.ts}

@@ -12,22 +12,58 @@ import { I as IDMap } from './id-map-DxQ3_gyA.js';
 interface Connection {
     sendMessage(msg: ServerMessage): void;
 }
-declare class Server {
+declare class Server<TAdditionalFiles extends ToolkitAdditionalFiles = Record<never, never>> {
     private readonly options;
     private readonly onNewConnection;
     private readonly onClosedConnection;
     private readonly onMessage;
     private readonly log?;
-    private readonly staticFiles;
-    private readonly entrypointFilename;
-    private title;
-    constructor(options: ToolkitOptions, onNewConnection: (connection: Connection) => void, onClosedConnection: (connection: Connection) => void, onMessage: (connection: Connection, message: ClientMessage) => void, log?: Logger | undefined);
+    private staticFiles;
+    private htmlContext;
+    private staticFilesInitPromise;
+    private readonly title;
+    constructor(options: ToolkitOptions<TAdditionalFiles>, onNewConnection: (connection: Connection) => void, onClosedConnection: (connection: Connection) => void, onMessage: (connection: Connection, message: ClientMessage) => void, log?: Logger | undefined);
+    private getEntrypointPaths;
+    private fileExists;
+    private ensureStaticFilesInitialized;
     handleHttpRequest: (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
-    private sendStaticFile;
+    private parsePathname;
+    private toRoutePath;
+    private toSiteRelativeUrl;
+    private createAssetUrls;
     handleWsConnection: <S extends WebSocket>(ws: S) => void;
 }
 
-interface ToolkitOptions {
+declare const FONTS: {
+    readonly materialSymbolsOutlined: "material-symbols-outlined.woff2";
+};
+
+type ToolkitStaticFile = {
+    contentType: string;
+    content: Buffer;
+};
+type ToolkitStaticFileResolver = () => Promise<ToolkitStaticFile>;
+type ToolkitAdditionalFiles = Record<string, ToolkitStaticFileResolver>;
+type ToolkitCoreAssetRelativePath = typeof FONTS.materialSymbolsOutlined | `${string}.js` | `${string}.js.map` | `${string}.css` | `${string}.css.map`;
+type ToolkitHtmlPageContext<TAdditionalFiles extends ToolkitAdditionalFiles> = {
+    title: string;
+    path: string;
+    coreAssets: {
+        materialSymbolsOutlined: string;
+        entrypointJs: string;
+        entrypointJsMap: string | null;
+        entrypointCss: string | null;
+        entrypointCssMap: string | null;
+    };
+    assetUrls: Record<ToolkitCoreAssetRelativePath | Extract<keyof TAdditionalFiles, string>, string>;
+};
+type ToolkitClockSyncOptions = {
+    /**
+     * How often the browser should request a ping in milliseconds.
+     */
+    pingIntervalMs: number;
+};
+interface ToolkitOptions<TAdditionalFiles extends ToolkitAdditionalFiles = Record<never, never>> {
     /**
      * What window title should the toolkit be initialized with?
      */
@@ -53,8 +89,10 @@ interface ToolkitOptions {
      * This is only needed if you have defined custom extensions,
      * and need to load custom frontend code that includes your extensions.
      *
-     * This will allow access to both the js file and the `.map.js` file,
-     * that matches this name.
+     * ArcaneJS expects an associated `.css` file with the same basename
+     * (for example `entrypoint.js` + `entrypoint.css`) so browser styles are
+     * served automatically. Source map files (`.js.map`, `.css.map`) are optional,
+     * and exposed when present.
      */
     entrypointJsFile?: string;
     /**
@@ -64,8 +102,29 @@ interface ToolkitOptions {
      * you can provide the path to the material-symbols-outlined.woff2 file here.
      */
     materialIconsFontFile?: string;
+    /**
+     * Additional static assets that should be exposed from the toolkit path.
+     *
+     * The object key is the relative request path (for example `styles/app.css`),
+     * and the loader returns the response payload and content type.
+     */
+    additionalFiles?: TAdditionalFiles;
+    /**
+     * Optional custom HTML renderer for the root page.
+     *
+     * Receives resolved site-relative URLs for all available static assets,
+     * including toolkit defaults and files provided by `additionalFiles`.
+     */
+    htmlPage?: (context: ToolkitHtmlPageContext<TAdditionalFiles>) => string | Promise<string>;
+    /**
+     * Enable browser/server clock synchronization support.
+     *
+     * When enabled, frontend clients will periodically ping the toolkit server
+     * and expose a calculated server clock offset in stage context.
+     */
+    clockSync?: false | ToolkitClockSyncOptions;
 }
-type InitializationOptions = 
+type InitializationOptions<TAdditionalFiles extends ToolkitAdditionalFiles = Record<never, never>> = 
 /** automatically start a simple  */
 {
     mode: 'automatic';
@@ -85,7 +144,7 @@ type InitializationOptions =
 /** Create a websocket server that attaches to an existing express and http server */
  | {
     mode: 'manual';
-    setup: (server: Server) => void;
+    setup: (server: Server<TAdditionalFiles>) => void;
 };
 
 declare abstract class Base<Namespace extends string, Proto extends BaseComponentProto<Namespace, string>, Props, CallPairs = any, CallActions extends string & keyof CallPairs = any> {
@@ -114,7 +173,7 @@ declare abstract class Base<Namespace extends string, Proto extends BaseComponen
     /** @hidden */
     updateTree(): void;
     /** @hidden */
-    abstract getProtoInfo(idMap: IDMap): Proto;
+    abstract getProtoInfo(idMap: IDMap, context: ToolkitRenderContext): Proto;
     /** @hidden */
     handleMessage(_message: AnyClientComponentMessage, _connection: ToolkitConnection): void;
     /** @hidden */
@@ -199,7 +258,7 @@ declare class Button extends Base<proto.CoreNamespace, proto.ButtonComponent, In
     setIcon: (icon: string | undefined | null) => this;
     setMode: (mode: ButtonMode) => this;
     /** @hidden */
-    getProtoInfo: (idMap: IDMap) => proto.ButtonComponent;
+    getProtoInfo: (idMap: IDMap, _context: ToolkitRenderContext) => proto.ButtonComponent;
     /** @hidden */
     handleCall: (call: AnyClientComponentCall, connection: ToolkitConnection) => Promise<true>;
 }
@@ -221,7 +280,7 @@ type Props = Partial<InternalProps>;
 declare class GroupHeader extends BaseParent<proto.CoreNamespace, proto.CoreComponent, Record<never, never>> {
     validateChildren: () => void;
     /** @hidden */
-    getProtoInfo: (idMap: IDMap) => proto.GroupHeaderComponent;
+    getProtoInfo: (idMap: IDMap, context: ToolkitRenderContext) => proto.GroupHeaderComponent;
 }
 /**
  * A collection of components, grouped in either a row or column. Can contain
@@ -245,7 +304,7 @@ declare class Group extends BaseParent<proto.CoreNamespace, proto.GroupComponent
     removeHeaderChild: (child: Button) => void;
     removeAllHeaderChildren: () => void;
     /** @hidden */
-    getProtoInfo: (idMap: IDMap) => proto.GroupComponent;
+    getProtoInfo: (idMap: IDMap, context: ToolkitRenderContext) => proto.GroupComponent;
     /** @hidden */
     handleMessage: (message: AnyClientComponentMessage, connection: ToolkitConnection) => void;
 }
@@ -253,6 +312,9 @@ declare class Group extends BaseParent<proto.CoreNamespace, proto.GroupComponent
 type ToolkitConnection = {
     uuid: string;
 };
+type ToolkitRenderContext = {
+    connection: ToolkitConnection;
+};
 type Events = {
     'new-connection': (connection: ToolkitConnection) => void;
     'closed-connection': (connection: ToolkitConnection) => void;
@@ -264,8 +326,9 @@ type ToolkitServerListenerOptions = {
 type ToolkitServerListener = {
     close: () => void;
 };
-declare class Toolkit implements Parent, Listenable<Events> {
+declare class Toolkit<TAdditionalFiles extends ToolkitAdditionalFiles = Record<never, never>> implements Parent, Listenable<Events> {
     private readonly options;
+    private readonly clockSync;
     /**
      * Mapping from components to unique IDs that identify them
      */
@@ -275,10 +338,10 @@ declare class Toolkit implements Parent, Listenable<Events> {
     /** @hidden */
     private readonly events;
     private readonly server;
-    constructor(options?: Partial<ToolkitOptions>);
+    constructor(options?: Partial<ToolkitOptions<TAdditionalFiles>>);
     addListener: <T extends keyof Events>(type: T, listener: Events[T]) => void;
     removeListener: <T extends keyof Events>(type: T, listener: Events[T]) => void;
-    start: (opts: InitializationOptions) => void;
+    start: (opts: InitializationOptions<TAdditionalFiles>) => void;
     listen: ({ port, host, }: ToolkitServerListenerOptions) => Promise<ToolkitServerListener>;
     setRoot: (group: Group) => void;
     log(): _arcanejs_protocol_logging.Logger | null;
@@ -291,4 +354,4 @@ declare class Toolkit implements Parent, Listenable<Events> {
     private onMessage;
 }
 
-export { type AnyComponent as A, Button as B, EventEmitter as E, Group as G, type InternalProps$1 as I, type Listenable as L, type Parent as P, Toolkit as T, type ToolkitConnection as a, type ToolkitServerListenerOptions as b, type ToolkitServerListener as c, type ToolkitOptions as d, GroupHeader as e, Base as f, BaseParent as g, type Events$2 as h, type ButtonMode as i, type Props$1 as j, type Events$1 as k, type InternalProps as l, type Props as m };
+export { type AnyComponent as A, Button as B, EventEmitter as E, Group as G, type InternalProps$1 as I, type Listenable as L, type Parent as P, Toolkit as T, type ToolkitConnection as a, type ToolkitRenderContext as b, type ToolkitServerListenerOptions as c, type ToolkitServerListener as d, type ToolkitAdditionalFiles as e, type ToolkitClockSyncOptions as f, type ToolkitCoreAssetRelativePath as g, type ToolkitHtmlPageContext as h, type ToolkitOptions as i, type ToolkitStaticFile as j, type ToolkitStaticFileResolver as k, GroupHeader as l, Base as m, BaseParent as n, type Events$2 as o, type ButtonMode as p, type Props$1 as q, type Events$1 as r, type InternalProps as s, type Props as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcanejs/toolkit",
-  "version": "6.0.1",
+  "version": "7.0.0",
   "private": false,
   "description": "Build web-accessible control interfaces for your long-running Node.js processes",
   "keywords": [
@@ -103,36 +103,34 @@
     "@types/express": "^5.0.0",
     "@types/lodash": "^4.17.10",
     "@types/node": "^20.11.24",
-    "@types/react": "^18",
-    "@types/react-dom": "^18",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
     "@types/ws": "^8.5.12",
     "check-export-map": "^1.3.1",
-    "esbuild": "^0.24.0",
     "eslint": "^8.57.0",
-    "react": "^18",
-    "react-dom": "18.3.1",
-    "styled-components": "^6.1.13",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "tsup": "^8.1.0",
     "typescript": "^5.3.3",
     "@arcanejs/eslint-config": "^0.0.0",
-    "@arcanejs/toolkit-frontend": "^0.9.0",
-    "@arcanejs/typescript-config": "^0.0.0"
+    "@arcanejs/toolkit-frontend": "^0.10.0",
+    "@arcanejs/typescript-config": "^0.0.0",
+    "@arcanejs/build-utils": "^0.1.1"
   },
   "dependencies": {
     "escape-html": "^1.0.3",
     "express": "^4.21.1",
-    "lodash": "^4.17.21",
+    "lodash": "^4.17.23",
     "material-symbols": "^0.25.0",
     "uuid": "^11.0.3",
     "ws": "^8.18.0",
-    "@arcanejs/diff": "^0.5.1",
-    "@arcanejs/protocol": "^0.7.0"
+    "@arcanejs/diff": "^0.5.2",
+    "@arcanejs/protocol": "^0.8.0"
   },
   "peerDependencies": {
-    "react": "^18",
-    "react-dom": "18.3.1",
-    "styled-components": "^6.1.13",
-    "@arcanejs/toolkit-frontend": "^0.9.0"
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "@arcanejs/toolkit-frontend": "^0.10.0"
   },
   "peerDependenciesMeta": {
     "@arcanejs/toolkit-frontend": {
@@ -143,9 +141,6 @@
     },
     "react-dom": {
       "optional": true
-    },
-    "styled-components": {
-      "optional": true
     }
   },
   "files": [
@@ -158,7 +153,7 @@
     "lint": "eslint . --max-warnings 0",
     "build": "rm -rf dist && pnpm build:backend && pnpm type-check:frontend && pnpm build:frontend && check-export-map",
     "build:backend": "tsup",
-    "build:frontend": "esbuild src/frontend/entrypoint-core.ts --bundle --sourcemap --outfile=dist/frontend/entrypoint.js",
+    "build:frontend": "arcane-build-frontend --entry src/frontend/entrypoint-core.ts --outfile dist/frontend/entrypoint.js --sourcemap --condition @arcanejs/source",
     "dev": "pnpm dev:backend & pnpm dev:frontend",
     "dev:backend": "pnpm build:backend --watch",
     "dev:frontend": "pnpm type-check:frontend:watch & pnpm build:frontend --watch",