@fluojs/studio 1.0.7 → 2.0.0

package/dist/viewer-server.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { readFile, realpath } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, resolve, sep } from 'node:path';
+const viewerHost = '127.0.0.1';
+/** Grace period before close destroys incomplete viewer-owned connections. */
+export const viewerServerCloseGracePeriodMs = 1_000;
+const mimeTypes = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.svg': 'image/svg+xml'
+};
+
+/** Supported parsed command-line request for the packaged Studio viewer. */
+
+/** Running local HTTP server for the packaged Studio viewer. */
+
+/**
+ * Parses command-line arguments for the packaged Studio viewer.
+ *
+ * @param arguments_ - Arguments passed after the viewer command name.
+ * @returns A help or launch request.
+ */
+export function parseStudioViewerArguments(arguments_) {
+  let port = 0;
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    switch (argument) {
+      case '--help':
+      case '-h':
+        return {
+          kind: 'help'
+        };
+      case '--port':
+        {
+          const portArgument = arguments_[index + 1];
+          if (portArgument === undefined) {
+            throw new Error('Missing port after --port.');
+          }
+          port = parsePort(portArgument);
+          index += 1;
+          break;
+        }
+      default:
+        throw new Error(`Unsupported viewer option: ${argument}`);
+    }
+  }
+  return {
+    kind: 'launch',
+    port
+  };
+}
+
+/**
+ * Starts an HTTP server that serves the installed Studio viewer artifacts.
+ *
+ * @param options - Local server options and the packaged artifact directory.
+ * @returns The running server and its local URL.
+ */
+export async function startStudioViewerServer(options) {
+  const viewerDirectory = await realpath(resolve(options.viewerDirectory));
+  const server = createServer((request, response) => {
+    void serveViewerAsset(request, response, viewerDirectory).catch(() => {
+      if (!response.headersSent) {
+        response.writeHead(500);
+      }
+      response.end();
+    });
+  });
+  const connections = new Set();
+  server.on('connection', socket => {
+    connections.add(socket);
+    socket.once('close', () => connections.delete(socket));
+  });
+  await listen(server, options.port);
+  const address = server.address();
+  if (address === null || typeof address === 'string') {
+    throw new Error('Studio viewer did not bind to a TCP port.');
+  }
+  let terminalClose;
+  return {
+    url: new URL(`http://${viewerHost}:${String(address.port)}/`),
+    close: () => {
+      terminalClose ??= close(server, connections);
+      return terminalClose;
+    }
+  };
+}
+async function serveViewerAsset(request, response, viewerDirectory) {
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    response.writeHead(405, {
+      allow: 'GET, HEAD'
+    }).end();
+    return;
+  }
+  let pathname;
+  try {
+    pathname = new URL(request.url ?? '/', `http://${viewerHost}`).pathname;
+  } catch {
+    response.writeHead(400).end();
+    return;
+  }
+  const relativePath = pathname === '/' ? 'index.html' : `.${pathname}`;
+  const assetPath = resolve(viewerDirectory, relativePath);
+  if (!assetPath.startsWith(`${viewerDirectory}${sep}`)) {
+    response.writeHead(404).end();
+    return;
+  }
+  try {
+    const resolvedAssetPath = await realpath(assetPath);
+    if (!resolvedAssetPath.startsWith(`${viewerDirectory}${sep}`)) {
+      response.writeHead(404).end();
+      return;
+    }
+    const content = await readFile(resolvedAssetPath);
+    const mimeType = mimeTypes[extname(resolvedAssetPath)] ?? 'application/octet-stream';
+    response.writeHead(200, {
+      'content-type': mimeType
+    }).end(request.method === 'HEAD' ? undefined : content);
+  } catch {
+    response.writeHead(404).end();
+  }
+}
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 0 || port > 65_535) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+  return port;
+}
+async function listen(server, port) {
+  await new Promise((resolveListen, rejectListen) => {
+    server.once('error', rejectListen);
+    server.listen({
+      host: viewerHost,
+      port
+    }, () => {
+      server.off('error', rejectListen);
+      resolveListen();
+    });
+  });
+}
+async function close(server, connections) {
+  const terminalClose = new Promise((resolveClose, rejectClose) => {
+    server.close(error => {
+      if (error === undefined) {
+        resolveClose();
+        return;
+      }
+      rejectClose(error);
+    });
+  });
+  const forceCloseTimer = setTimeout(() => {
+    for (const connection of connections) {
+      connection.destroy();
+    }
+  }, viewerServerCloseGracePeriodMs);
+  try {
+    await terminalClose;
+  } finally {
+    clearTimeout(forceCloseTimer);
+  }
+}
+
+/**
+ * Runs the executable Studio viewer command against a packaged artifact directory.
+ *
+ * @param arguments_ - Arguments passed after the executable name.
+ * @param viewerDirectory - Installed directory containing the viewer HTML assets.
+ * @returns A Promise that resolves after help output or successful local server launch.
+ */
+export async function runStudioViewerCli(arguments_, viewerDirectory) {
+  const request = parseStudioViewerArguments(arguments_);
+  switch (request.kind) {
+    case 'help':
+      process.stdout.write('Usage: fluo-studio-viewer [--port <0-65535>]\n');
+      return;
+    case 'launch':
+      {
+        const server = await startStudioViewerServer({
+          port: request.port,
+          viewerDirectory
+        });
+        process.stdout.write(`Fluo Studio viewer: ${server.url.href}\nPress Ctrl+C to stop.\n`);
+        return;
+      }
+  }
+}

package/package.json

@@ -9,7 +9,7 @@
     "module-graph",
     "devtools"
   ],
-  "version": "1.0.7",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,12 +18,15 @@
     "directory": "packages/studio"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
+  "bin": {
+    "fluo-studio-viewer": "./dist/viewer-cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -42,22 +45,23 @@
   ],
   "dependencies": {
     "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "@fluojs/runtime": "^1.1.8"
+    "react-dom": "^19.2.6"
   },
   "devDependencies": {
+    "@playwright/test": "^1.61.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "happy-dom": "^20.9.0",
-    "vitest": "^3.2.4",
+    "vitest": "^4.1.11",
     "@fluojs-internal/tooling-vite": "^0.0.1"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
-    "build": "pnpm exec vite build && pnpm exec babel src/contracts.ts src/index.ts --extensions .ts --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "build": "pnpm exec vite build && pnpm exec babel src/contracts.ts src/index.ts src/viewer-server.ts src/viewer-cli.ts --extensions .ts --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
     "dev": "pnpm exec vite",
     "preview": "pnpm exec vite preview",
-    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test:browser": "pnpm build && pnpm exec playwright test -c playwright.config.ts",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit && pnpm exec tsc -p playwright.tsconfig.json --noEmit",
     "test": "pnpm exec vitest run -c vitest.config.ts",
     "test:watch": "pnpm exec vitest -c vitest.config.ts"
   }