@opencraw/studio 0.0.2

package/dist/index.esm.js

@@ -0,0 +1,886 @@
+import { normalize, sep, join, extname, dirname, resolve } from 'node:path';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { randomBytes, createHash } from 'node:crypto';
+import { BrowserClient, HttpClient, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, RecipeBindingError, RecipeValidationError } from '@opencraw/core';
+import { writeFile } from 'node:fs/promises';
+import { existsSync, createReadStream } from 'node:fs';
+
+/** A budget for a sample run; never authored into a recipe, only asked for by the caller. */
+const sampleBudgetSchema = z.object({
+  maxRecords: z.number().int().positive().optional(),
+  maxPages: z.number().int().positive().optional(),
+  maxMs: z.number().int().positive().optional()
+});
+/** Opens a recipe folder: the server reads it and answers with a `WorkspaceView`. */
+const openWorkspaceCommandSchema = z.object({
+  type: z.literal('open-workspace'),
+  folder: z.string().min(1)
+});
+/** Runs one input recipe under a budget, streaming `trace-line` and `record` events, ending in `run-finished`. */
+const runSampleCommandSchema = z.object({
+  type: z.literal('run-sample'),
+  recipeId: z.string().min(1),
+  budget: sampleBudgetSchema.optional()
+});
+/** Closes the crawler of the run in progress, if any; a no-op otherwise. */
+const stopRunCommandSchema = z.object({
+  type: z.literal('stop-run')
+});
+/** Writes a recipe file: the whole object, pretty-printed by the server (see `recipe-workspace`). */
+const saveRecipeCommandSchema = z.object({
+  type: z.literal('save-recipe'),
+  path: z.string().min(1),
+  recipe: z.record(z.string(), z.unknown())
+});
+/** Fetches the HTML of an input recipe's start page, as the engine would see it. */
+const fetchStartPageCommandSchema = z.object({
+  type: z.literal('fetch-start-page'),
+  recipeId: z.string().min(1)
+});
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema]);
+
+/** Why a sample run stopped before finishing on its own; mirrors `@opencraw/core`'s `RecipeReport.stoppedBy`. */
+const stoppedBySchema = z.enum(['sample-maxRecords', 'sample-maxPages', 'sample-maxMs']);
+/** One line of the engine's own trace output (`traceLine`), streamed as a sample run proceeds. */
+const traceLineEventSchema = z.object({
+  type: z.literal('trace-line'),
+  line: z.string()
+});
+/** One record a sample run emitted. */
+const recordEventSchema = z.object({
+  type: z.literal('record'),
+  recipeId: z.string(),
+  key: z.string().nullable(),
+  data: z.record(z.string(), z.unknown())
+});
+/** A sample run ended: how many records, and why it stopped when it did not finish on its own. */
+const runFinishedEventSchema = z.object({
+  type: z.literal('run-finished'),
+  recipeId: z.string(),
+  emitted: z.number(),
+  rejected: z.number(),
+  duplicates: z.number(),
+  durationMs: z.number(),
+  error: z.string().optional(),
+  stoppedBy: stoppedBySchema.optional()
+});
+/** The workspace's recipes changed on disk (a save, or a future watcher) and should be re-fetched. */
+const workspaceChangedEventSchema = z.object({
+  type: z.literal('workspace-changed')
+});
+const studioEventSchema = z.discriminatedUnion('type', [traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema]);
+
+/** One problem found on a recipe file, with the JSON path it lives at. */
+const recipeIssueSchema = z.object({
+  path: z.string(),
+  message: z.string(),
+  kind: z.enum(['validation', 'binding'])
+});
+/** One recipe file in an opened workspace. */
+const recipeListingSchema = z.object({
+  file: z.string(),
+  kind: z.enum(['input', 'output', 'unknown']),
+  id: z.string().optional(),
+  issues: z.array(recipeIssueSchema),
+  /** The file's JSON, pretty-printed: the JSON tab's starting text (see `save-recipe` for how an edit is written back). */
+  text: z.string()
+});
+/** What `open-workspace` answers with: every recipe file directly inside the folder. */
+const workspaceViewSchema = z.object({
+  folder: z.string(),
+  recipes: z.array(recipeListingSchema)
+});
+
+/** One record of a sample run's result, kept for the Records tab. */
+const sampleRunRecordSchema = z.object({
+  key: z.string().nullable(),
+  data: z.record(z.string(), z.unknown())
+});
+/** The last sample run's result, for a client that opens the UI after it finished. */
+const sampleRunViewSchema = z.object({
+  recipeId: z.string(),
+  emitted: z.number(),
+  rejected: z.number(),
+  duplicates: z.number(),
+  durationMs: z.number(),
+  error: z.string().optional(),
+  stoppedBy: stoppedBySchema.optional(),
+  records: z.array(sampleRunRecordSchema),
+  trace: z.array(z.string())
+});
+
+/** What `fetch-start-page` answers with. */
+const startPageViewSchema = z.object({
+  html: z.string()
+});
+
+/** The cookie set on the page's own document response, so its own asset and API requests carry the token too. */
+const TOKEN_COOKIE = 'opencraw_token';
+/** A random token, generated once at server startup and required on every request. */
+function generateToken() {
+  return randomBytes(24).toString('hex');
+}
+/**
+ * The token a request carries, checked in this order: the `x-opencraw-token`
+ * header, the `token` query param, the studio's own cookie (set after the
+ * first authenticated document request, so a browser's own asset and API
+ * requests need not repeat the query param).
+ *
+ * @param request - The incoming request.
+ * @param query - Its URL's query string, parsed.
+ * @returns The token found, or `undefined`.
+ */
+function tokenOf(request, query) {
+  const header = request.headers['x-opencraw-token'];
+  if (typeof header === 'string') return header;
+  const fromQuery = query.get('token');
+  return fromQuery ?? cookieToken(request.headers.cookie);
+}
+/**
+ * Whether a request proves it holds the server's token.
+ *
+ * @param expected - The server's token.
+ * @param request - The incoming request.
+ * @param query - Its URL's query string, parsed.
+ * @returns Whether the request is authorized.
+ */
+function isAuthorized(expected, request, query) {
+  return tokenOf(request, query) === expected;
+}
+function cookieToken(header) {
+  if (header === undefined) return undefined;
+  for (const part of header.split(';')) {
+    const [name, ...rest] = part.trim().split('=');
+    if (name === TOKEN_COOKIE) return rest.join('=');
+  }
+  return undefined;
+}
+
+/**
+ * Fetches an input recipe's start page as the engine would see it: a fresh
+ * Playwright page in web mode, core's HTTP client in api mode. Returns plain
+ * text: the page's HTML, or a readable rendering of a non-HTML api response.
+ * No rewriting, no script stripping, no node ids yet: that is phase 2's
+ * `page-snapshot` proper (studio plan, #91). Provisional for phase 0 in two
+ * ways, both worth knowing before relying on it: it opens a bare page
+ * without running the recipe's own steps first, so a start point behind a
+ * `session.bootstrap` login shows what an anonymous visitor sees; and it
+ * launches a fresh browser or HTTP context per call, one page then closes
+ * it, rather than reusing whatever the last sample run had open.
+ *
+ * @param input - The input recipe; only `mode` and the first `start` point are used.
+ * @param browser - Browser launch settings for web mode (an executable path override, headless…).
+ * @returns The page's content as plain text.
+ * @throws Error when the recipe has no start point.
+ */
+async function fetchStartPage(input, browser) {
+  const point = input.start[0];
+  if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
+  return input.mode === 'web' ? fetchWeb(point.url, browser) : fetchApi(point.url);
+}
+async function fetchWeb(url, browser) {
+  const client = await BrowserClient.launch(browser);
+  try {
+    const session = await client.newSession();
+    try {
+      await session.page.goto(url);
+      return await session.page.content();
+    } finally {
+      await session.close();
+    }
+  } finally {
+    await client.close();
+  }
+}
+async function fetchApi(url) {
+  const client = await HttpClient.open({});
+  try {
+    const response = await client.send({
+      url
+    });
+    return textOf(response.body);
+  } finally {
+    await client.dispose();
+  }
+}
+/** Every body kind the studio can show as text today; others get a placeholder rather than a crash. */
+function textOf(body) {
+  if (body.kind === 'html') return body.html;
+  if (body.kind === 'text') return body.text;
+  if (body.kind === 'json') return JSON.stringify(body.data, null, 2);
+  return `[${body.kind} document: the content pane shows HTML and JSON responses for now]`;
+}
+
+/**
+ * Finds and parses one input recipe of a workspace folder, and the output
+ * recipe it names.
+ *
+ * @param folder - The workspace folder.
+ * @param recipeId - The input recipe's id.
+ * @returns The parsed pair.
+ * @throws RecipeValidationError when either recipe does not parse.
+ * @throws Error when the input or its output is not in the folder.
+ */
+async function loadRecipePair(folder, recipeId) {
+  const documents = await readRecipeSource(folder);
+  const inputDocument = documents.find(document => kindOf(document.content) === 'input' && idOf(document.content) === recipeId);
+  if (inputDocument === undefined) throw new Error(`no input recipe "${recipeId}" in this workspace`);
+  const input = parseInputRecipe(inputDocument.content, inputDocument.source);
+  const outputDocument = documents.find(document => kindOf(document.content) === 'output' && idOf(document.content) === input.output);
+  if (outputDocument === undefined) throw new Error(`no output recipe "${input.output}" in this workspace`);
+  return {
+    input,
+    output: parseOutputRecipe(outputDocument.content, outputDocument.source)
+  };
+}
+function kindOf(content) {
+  return content?.kind;
+}
+function idOf(content) {
+  return content?.id;
+}
+
+/**
+ * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
+ * each `record:emit` carries its data), an in-memory sink, and `budget` as
+ * the crawler's `sample` (`@opencraw/core`'s `CrawlOptions.sample`, #89).
+ * Every engine event becomes a trace line with the same `traceLine`
+ * formatter the cli's `--trace` uses; every emitted record reaches
+ * `callbacks.onRecord` as it happens, not only in the final result.
+ *
+ * @param folder - The workspace folder the recipe lives in.
+ * @param recipeId - The input recipe to run.
+ * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
+ * @param callbacks - Where trace lines and records go as the run proceeds.
+ * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
+ * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
+ */
+async function runSample(folder, recipeId, budget, callbacks) {
+  const {
+    input,
+    output
+  } = await loadRecipePair(folder, recipeId);
+  const set = bindRecipeSet(output, [input]);
+  const sink = memorySink();
+  const crawler = createCrawler({
+    sink,
+    debug: true,
+    sample: budget,
+    onEvent: event => {
+      const line = traceLine(event);
+      if (line !== undefined) callbacks.onTraceLine(line);
+      if (event.type === 'record:emit') callbacks.onRecord({
+        key: event.key,
+        data: event.data
+      });
+    }
+  });
+  const result = runToResult(crawler, set, sink);
+  return {
+    stop: () => crawler.close(),
+    result
+  };
+}
+async function runToResult(crawler, set, sink) {
+  try {
+    const report = await crawler.run(set);
+    const recipe = report.recipes[0];
+    return {
+      recipeId: recipe.recipeId,
+      emitted: recipe.emitted,
+      rejected: recipe.rejected,
+      duplicates: recipe.duplicates,
+      durationMs: recipe.durationMs,
+      error: recipe.error,
+      stoppedBy: recipe.stoppedBy,
+      records: sink.records.map(record => ({
+        key: record.key,
+        data: record.data
+      }))
+    };
+  } finally {
+    await crawler.close();
+  }
+}
+
+/**
+ * Handles `fetch-start-page`: loads the named input recipe from the current
+ * workspace and fetches its start point (see `page-snapshot`'s own caveats:
+ * no session bootstrap, a fresh browser or HTTP context per call).
+ *
+ * @param state - The server state: `folder` must already be set.
+ * @param command - The command.
+ * @returns The page's content as plain text.
+ * @throws Error when no workspace is open, or the recipe cannot be found or loaded.
+ */
+async function handleFetchStartPage(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  const {
+    input
+  } = await loadRecipePair(state.folder, command.recipeId);
+  const html = await fetchStartPage(input);
+  return {
+    html
+  };
+}
+
+/**
+ * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
+ * (core's own directory reading, so relative `file:` URLs resolve the same
+ * way a real run would), parsed and, for each output recipe found, bound to
+ * the input recipes that name it. Nothing throws for a bad recipe or a
+ * recipe that does not bind: every problem is reported on its file with the
+ * JSON path core already computes, exactly as `opencraw validate` prints it.
+ *
+ * @param folder - The workspace folder.
+ * @returns Every recipe file found, each with its validation and binding issues.
+ * @throws Error when the folder does not exist or cannot be read.
+ */
+async function openWorkspace(folder) {
+  const documents = await readRecipeSource(folder);
+  const entries = documents.map(document => parseDocument(document));
+  const outputs = entries.filter(isParsed('output'));
+  const inputs = entries.filter(isParsed('input'));
+  for (const output of outputs) bindOutput(output, inputs);
+  for (const input of inputs) {
+    if (outputs.every(output => output.recipe.id !== input.recipe.output)) {
+      input.issues.push({
+        path: 'output',
+        message: `no output recipe "${input.recipe.output}" in this workspace`,
+        kind: 'binding'
+      });
+    }
+  }
+  return {
+    folder,
+    recipes: entries.map(({
+      file,
+      kind,
+      id,
+      issues,
+      content
+    }) => ({
+      file,
+      kind,
+      id,
+      issues,
+      text: `${JSON.stringify(content, null, 2)}\n`
+    }))
+  };
+}
+/** Binds one output recipe to the inputs that name it, filing every binding issue back on the recipe it names. */
+function bindOutput(output, inputs) {
+  const matching = inputs.filter(input => input.recipe.output === output.recipe.id);
+  try {
+    bindRecipeSet(output.recipe, matching.map(input => input.recipe));
+  } catch (error) {
+    if (!(error instanceof RecipeBindingError)) throw error;
+    for (const issue of error.issues) {
+      const target = issue.recipeId === output.recipe.id ? output : matching.find(input => input.recipe.id === issue.recipeId);
+      target?.issues.push({
+        path: issue.path,
+        message: issue.message,
+        kind: 'binding'
+      });
+    }
+  }
+}
+function isParsed(kind) {
+  return entry => entry.kind === kind && entry.recipe !== undefined;
+}
+function parseDocument(document) {
+  const kind = document.content?.kind;
+  if (kind === 'output') return parseOne(document.source, document.content, 'output', parseOutputRecipe);
+  if (kind === 'input') return parseOne(document.source, document.content, 'input', parseInputRecipe);
+  return {
+    file: document.source,
+    kind: 'unknown',
+    content: document.content,
+    issues: [{
+      path: 'kind',
+      message: '"kind" is missing or not "input"/"output"',
+      kind: 'validation'
+    }]
+  };
+}
+function parseOne(file, content, kind, parse) {
+  try {
+    const recipe = parse(content, file);
+    return {
+      file,
+      kind,
+      content,
+      id: recipe.id,
+      issues: [],
+      recipe
+    };
+  } catch (error) {
+    if (!(error instanceof RecipeValidationError)) throw error;
+    return {
+      file,
+      kind,
+      content,
+      issues: error.issues.map(issue => ({
+        path: issue.path === '' ? '(root)' : issue.path,
+        message: issue.message,
+        kind: 'validation'
+      }))
+    };
+  }
+}
+
+/**
+ * Writes a recipe back to its file: pretty JSON, a 2-space indent, a
+ * trailing newline. Phase 0 takes the JSON tab's whole parsed object rather
+ * than a patch, so this is a full replacement, not a splice: loading a file
+ * the studio has not touched and saving it again keeps every key, value and
+ * key order (`JSON.parse` preserves insertion order, and `JSON.stringify`
+ * writes it back), but not necessarily the file's exact original formatting
+ * (alignment, how arrays wrap, a trailing comment). Byte-identical
+ * round-trip for a hand-formatted file is future work; see this file's test
+ * for what is guaranteed today.
+ *
+ * @param path - The recipe file to write.
+ * @param recipe - The whole recipe object.
+ */
+async function saveRecipe(path, recipe) {
+  await writeFile(path, `${JSON.stringify(recipe, null, 2)}\n`, 'utf8');
+}
+
+/** @returns Fresh state for a new server instance: no workspace open, no run, no sockets. */
+function createStudioState() {
+  return {
+    sockets: new Set()
+  };
+}
+/**
+ * Sends one event to every connected client. A socket that errors while
+ * sending (gone away without a clean close yet reaching us) is dropped
+ * rather than left to fail every later broadcast too.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param event - The event to send.
+ */
+function broadcast(state, event) {
+  const text = JSON.stringify(event);
+  for (const socket of state.sockets) {
+    try {
+      socket.send(text);
+    } catch {
+      state.sockets.delete(socket);
+    }
+  }
+}
+
+/**
+ * Handles `open-workspace`: reads the folder, remembers it as the server's
+ * current workspace (every later command that names a recipe resolves it
+ * against this folder), and tells every connected client the workspace changed.
+ *
+ * @param state - The server state to update.
+ * @param command - The command.
+ * @returns The workspace's recipes and their issues.
+ */
+async function handleOpenWorkspace(state, command) {
+  const view = await openWorkspace(command.folder);
+  state.folder = command.folder;
+  broadcast(state, {
+    type: 'workspace-changed'
+  });
+  return view;
+}
+
+/**
+ * Handles `run-sample`: stops whatever sample was still running (one run at
+ * a time), starts the new one, and returns once it has started, not once it
+ * finishes: `trace-line` and `record` stream over the WebSocket as the run
+ * proceeds, and `run-finished` closes it out.
+ *
+ * @param state - The server state: `folder` must already be set (`open-workspace` first).
+ * @param command - The command.
+ * @returns `{ started: true }` once the run has begun.
+ * @throws Error when no workspace is open, or the recipe cannot be loaded or bound.
+ */
+async function handleRunSample(state, command) {
+  if (state.folder === undefined) throw new Error('open a workspace first');
+  await state.activeRun?.stop();
+  const handle = await runSample(state.folder, command.recipeId, command.budget, {
+    onTraceLine: line => {
+      broadcast(state, {
+        type: 'trace-line',
+        line
+      });
+    },
+    onRecord: record => {
+      broadcast(state, {
+        type: 'record',
+        recipeId: command.recipeId,
+        key: record.key,
+        data: record.data
+      });
+    }
+  });
+  state.activeRun = handle;
+  void handle.result.then(result => {
+    if (state.activeRun === handle) state.activeRun = undefined;
+    broadcast(state, {
+      type: 'run-finished',
+      recipeId: result.recipeId,
+      emitted: result.emitted,
+      rejected: result.rejected,
+      duplicates: result.duplicates,
+      durationMs: result.durationMs,
+      error: result.error,
+      stoppedBy: result.stoppedBy
+    });
+  });
+  return {
+    started: true
+  };
+}
+/**
+ * Handles `stop-run`: closes the crawler of the run in progress, if any.
+ * `run-finished` still follows once the interrupted run's promise settles.
+ *
+ * @param state - The server state holding the active run, if any.
+ * @param _command - The command (carries nothing beyond its type).
+ * @returns Whether a run was actually in progress to stop.
+ */
+async function handleStopRun(state, _command) {
+  const run = state.activeRun;
+  if (run === undefined) return {
+    stopped: false
+  };
+  await run.stop();
+  return {
+    stopped: true
+  };
+}
+
+/**
+ * Handles `save-recipe`: writes the file (see `recipe-workspace/save-recipe.use-case.ts`
+ * for the pretty-printing and its round-trip guarantee), then tells every
+ * connected client the workspace changed, so the UI can re-fetch it.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param command - The command: the file path and the whole recipe object.
+ * @returns `{ saved: true }` once the write has completed.
+ */
+async function handleSaveRecipe(state, command) {
+  await saveRecipe(command.path, command.recipe);
+  broadcast(state, {
+    type: 'workspace-changed'
+  });
+  return {
+    saved: true
+  };
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+};
+/**
+ * Serves the built UI from `root` (`packages/studio/dist/ui`, `apps/studio-ui`'s
+ * build output): the requested path if it exists as a file, `index.html`
+ * otherwise, so a client-side route (or the bare `/`) always gets the SPA's
+ * shell. `root` not existing at all (the UI has not been built) answers 404
+ * with a hint rather than a stack trace.
+ *
+ * @param root - The built UI's folder.
+ * @param pathname - The request's URL path.
+ * @param response - The response to write to.
+ */
+function serveStatic(root, pathname, response) {
+  const safe = normalize(pathname).split(sep).filter(segment => segment !== '..').join(sep);
+  const candidate = join(root, safe);
+  const file = safe !== '' && safe !== sep && existsSync(candidate) ? candidate : join(root, 'index.html');
+  if (!existsSync(file)) {
+    response.writeHead(404, {
+      'content-type': 'text/plain; charset=utf-8'
+    });
+    response.end('the studio UI has not been built yet: run `nx build studio-ui`');
+    return;
+  }
+  response.writeHead(200, {
+    'content-type': MIME[extname(file)] ?? 'application/octet-stream'
+  });
+  createReadStream(file).pipe(response);
+}
+
+/** RFC 6455's fixed handshake suffix. */
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+/**
+ * Accepts one WebSocket upgrade on the raw socket `node:http` hands an
+ * `upgrade` listener, implementing just enough of RFC 6455 for the studio's
+ * own one-directional event stream: the server sends small JSON text
+ * frames, the client sends none (commands go over `POST /api/command`). No
+ * `ws` dependency: this is deliberately small rather than general-purpose.
+ *
+ * @param request - The upgrade request (its `Sec-WebSocket-Key` header).
+ * @param socket - The raw, already-connected socket.
+ * @returns The connection: `send`, `close`, and where messages and the close go.
+ */
+function acceptWebSocket(request, socket) {
+  const key = request.headers['sec-websocket-key'] ?? '';
+  const accept = createHash('sha1').update(key + WS_GUID).digest('base64');
+  socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+  const messageHandlers = [];
+  const closeHandlers = [];
+  let buffer = Buffer.alloc(0);
+  socket.on('data', chunk => {
+    buffer = consumeFrames(Buffer.concat([buffer, chunk]), messageHandlers, closeHandlers, socket);
+  });
+  socket.on('close', () => {
+    for (const handler of closeHandlers) handler();
+  });
+  socket.on('error', () => {
+    for (const handler of closeHandlers) handler();
+  });
+  return {
+    send: text => {
+      if (!socket.destroyed) socket.write(frame(text));
+    },
+    close: () => {
+      socket.end();
+    },
+    onMessage: handler => {
+      messageHandlers.push(handler);
+    },
+    onClose: handler => {
+      closeHandlers.push(handler);
+    }
+  };
+}
+/** One unmasked text frame (server-to-client frames are never masked). */
+function frame(text) {
+  const payload = Buffer.from(text, 'utf8');
+  const {
+    length
+  } = payload;
+  const header = length < 126 ? Buffer.from([0x81, length]) : length < 65536 ? Buffer.concat([Buffer.from([0x81, 126]), lengthBytes(length, 2)]) : Buffer.concat([Buffer.from([0x81, 127]), lengthBytes(length, 8)]);
+  return Buffer.concat([header, payload]);
+}
+function lengthBytes(value, size) {
+  const buffer = Buffer.alloc(size);
+  if (size === 2) buffer.writeUInt16BE(value);else buffer.writeBigUInt64BE(BigInt(value));
+  return buffer;
+}
+/**
+ * Reads every complete frame at the front of `buffer`, dispatching text and
+ * close frames, and returns what is left (a partial frame still arriving).
+ */
+function consumeFrames(buffer, messageHandlers, closeHandlers, socket) {
+  let rest = buffer;
+  for (;;) {
+    if (rest.length < 2) return rest;
+    const opcode = rest[0] & 0x0F;
+    const masked = (rest[1] & 0x80) !== 0;
+    let length = rest[1] & 0x7F;
+    let offset = 2;
+    if (length === 126) {
+      if (rest.length < offset + 2) return rest;
+      length = rest.readUInt16BE(offset);
+      offset += 2;
+    } else if (length === 127) {
+      if (rest.length < offset + 8) return rest;
+      length = Number(rest.readBigUInt64BE(offset));
+      offset += 8;
+    }
+    const maskLength = masked ? 4 : 0;
+    if (rest.length < offset + maskLength + length) return rest;
+    const mask = masked ? rest.subarray(offset, offset + 4) : undefined;
+    offset += maskLength;
+    const payload = Buffer.from(rest.subarray(offset, offset + length));
+    if (mask !== undefined) for (let index = 0; index < payload.length; index += 1) payload[index] ^= mask[index % 4];
+    offset += length;
+    if (opcode === 0x8) {
+      for (const handler of closeHandlers) handler();
+      socket.end();
+      return Buffer.alloc(0);
+    }
+    // 0x1 text; ping/pong and continuation frames are ignored: every message here fits in one text frame.
+    if (opcode === 0x1) for (const handler of messageHandlers) handler(payload.toString('utf8'));
+    rest = rest.subarray(offset);
+  }
+}
+
+/** Where the UI Vite builds into, relative to this package: `dist/ui` next to the bundled server. */
+function defaultUiRoot() {
+  return join(dirname(fileURLToPath(import.meta.url)), 'ui');
+}
+/**
+ * Starts the studio's HTTP server: one `POST /api/command` for every
+ * command `studio-api` defines, `GET /ws` for the event stream, and the
+ * built UI for everything else. Binds `127.0.0.1` only; every request needs
+ * the token (`access-token.policy.ts`) — as a header, a query param, or the
+ * cookie the server sets once a document request proves the query param.
+ *
+ * @param options - The UI root and the port; both default sensibly.
+ * @returns The running server.
+ */
+async function startStudioServer(options = {}) {
+  const token = generateToken();
+  const uiRoot = options.uiRoot ?? defaultUiRoot();
+  const state = createStudioState();
+  if (options.initialFolder !== undefined) state.folder = options.initialFolder;
+  const server = createServer((request, response) => {
+    void handleRequest(request, response, token, state, uiRoot);
+  });
+  server.on('upgrade', (request, socket) => {
+    handleUpgrade(request, socket, token, state);
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(options.port ?? 0, '127.0.0.1', resolve);
+  });
+  const address = server.address();
+  const port = typeof address === 'object' && address !== null ? address.port : 0;
+  const folderParam = options.initialFolder === undefined ? '' : `&folder=${encodeURIComponent(options.initialFolder)}`;
+  return {
+    url: `http://127.0.0.1:${port}/?token=${token}${folderParam}`,
+    token,
+    close: () => stop(server, state)
+  };
+}
+async function stop(server, state) {
+  await state.activeRun?.stop();
+  server.closeAllConnections();
+  await new Promise((resolve, reject) => {
+    server.close(error => error === undefined ? resolve() : reject(error));
+  });
+}
+async function handleRequest(request, response, token, state, uiRoot) {
+  const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+  if (!isAuthorized(token, request, url.searchParams)) {
+    response.writeHead(401, {
+      'content-type': 'application/json'
+    });
+    response.end(JSON.stringify({
+      error: 'missing or invalid token'
+    }));
+    return;
+  }
+  if (url.pathname === '/api/command' && request.method === 'POST') {
+    await handleCommand(request, response, state);
+    return;
+  }
+  if (url.pathname === '/' && url.searchParams.get('token') !== null) response.setHeader('set-cookie', `${TOKEN_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/`);
+  serveStatic(uiRoot, url.pathname, response);
+}
+async function handleCommand(request, response, state) {
+  let command;
+  try {
+    const body = JSON.parse(await bodyOf(request));
+    const parsed = studioCommandSchema.safeParse(body);
+    if (!parsed.success) {
+      respondJson(response, 400, {
+        error: parsed.error.message
+      });
+      return;
+    }
+    command = parsed.data;
+  } catch (error) {
+    respondJson(response, 400, {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return;
+  }
+  try {
+    respondJson(response, 200, await dispatch(command, state));
+  } catch (error) {
+    respondJson(response, 500, {
+      error: error instanceof Error ? error.message : String(error)
+    });
+  }
+}
+function dispatch(command, state) {
+  switch (command.type) {
+    case 'open-workspace':
+      {
+        return handleOpenWorkspace(state, command);
+      }
+    case 'run-sample':
+      {
+        return handleRunSample(state, command);
+      }
+    case 'stop-run':
+      {
+        return handleStopRun(state);
+      }
+    case 'save-recipe':
+      {
+        return handleSaveRecipe(state, command);
+      }
+    case 'fetch-start-page':
+      {
+        return handleFetchStartPage(state, command);
+      }
+  }
+}
+function respondJson(response, status, body) {
+  response.writeHead(status, {
+    'content-type': 'application/json'
+  });
+  response.end(JSON.stringify(body));
+}
+function bodyOf(request) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    request.on('data', chunk => {
+      body += chunk.toString('utf8');
+    });
+    request.on('end', () => {
+      resolve(body);
+    });
+    request.on('error', reject);
+  });
+}
+function handleUpgrade(request, socket, token, state) {
+  const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+  if (url.pathname !== '/ws' || !isAuthorized(token, request, url.searchParams)) {
+    socket.destroy();
+    return;
+  }
+  const connection = acceptWebSocket(request, socket);
+  state.sockets.add(connection);
+  connection.onClose(() => {
+    state.sockets.delete(connection);
+  });
+}
+
+/**
+ * Runs `opencraw-studio`: starts the server, opens `folder` (if given) as
+ * the workspace right away, and prints the URL with the token, the way
+ * `docs/research/recipe-studio.md` §2 shows it: `http://127.0.0.1:<port>/?token=…`.
+ * The process stays up (the server keeps the event loop alive) until it is
+ * interrupted (Ctrl+C).
+ *
+ * @param argv - Arguments after the program name: an optional recipe folder, `.` when omitted.
+ */
+async function main(argv) {
+  const folder = resolve(argv[0] ?? '.');
+  const server = await startStudioServer({
+    initialFolder: folder
+  });
+  process.stdout.write(`OpenCraw Studio: ${server.url}\n`);
+  process.stdout.write(`Workspace: ${folder}\n`);
+  const shutdown = () => {
+    void server.close();
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+export { fetchStartPage, fetchStartPageCommandSchema, loadRecipePair, main, openWorkspace, openWorkspaceCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveRecipe, saveRecipeCommandSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, traceLineEventSchema, workspaceChangedEventSchema, workspaceViewSchema };
+//# sourceMappingURL=index.esm.js.map