sailfork / t3code-github / apps/ server/ src/ htmlRender/ HtmlRender.ts

import type { ThreadId } from "@t3tools/contracts";
import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
import * as HostProcess from "@t3tools/shared/HostProcess";
import {
  clampHtmlRenderHeight,
  HTML_RENDER_COLUMN_WIDTH,
  HTML_RENDER_MAX_TITLE_LENGTH,
  HTML_RENDER_MEASURE_FONTS,
  HTML_RENDER_MEASURE_WIDTHS,
  htmlRenderTheme,
  htmlRenderThemeFragment,
  injectHtmlRenderBootstrap,
  type HtmlRenderReference,
} from "@t3tools/shared/htmlRender";
import {
  T3_CODE_DARK_THEME_COLORS,
  T3_CODE_LIGHT_THEME_COLORS,
  type ThemeAppearance,
} from "@t3tools/shared/themePalettes";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import type * as Path from "effect/Path";
import * as Schema from "effect/Schema";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import type * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";

import { resolveAttachmentRelativePath } from "../attachmentPaths.ts";
import { createAttachmentId } from "../attachmentStore.ts";
import { resolveRootCliCommand } from "../cli/invocation.ts";
import * as ServerConfig from "../config.ts";
import * as HeadlessChrome from "./headlessChrome.ts";
import * as PreviewBrowser from "../preview/PreviewBrowser.ts";
import * as PreviewBrowserHost from "../preview/PreviewBrowserHost.ts";

const MIB = 1024 * 1024;
const MAX_IMAGE_BYTES = 10 * MIB;
const MAX_PAGE_BYTES = 25 * MIB;
const formatMib = (bytes: number) => `${(bytes / MIB).toFixed(1)} MiB`;

export class HtmlRenderImagesNotFoundError extends Schema.TaggedError<HtmlRenderImagesNotFoundError>()(
  "HtmlRenderImagesNotFoundError",
  { paths: Schema.Array(Schema.String) },
) {
  override get message(): string {
    return `These local images could not be read: ${this.paths.join(", ")}. Use absolute paths to existing image files, or remove them.`;
  }
}

export class HtmlRenderImageTooLargeError extends Schema.TaggedError<HtmlRenderImageTooLargeError>()(
  "HtmlRenderImageTooLargeError",
  { path: Schema.String, sizeBytes: Schema.Number },
) {
  override get message(): string {
    return `${this.path} is ${formatMib(this.sizeBytes)}; each local image must be at most ${formatMib(MAX_IMAGE_BYTES)}.`;
  }
}

export class HtmlRenderPageTooLargeError extends Schema.TaggedError<HtmlRenderPageTooLargeError>()(
  "HtmlRenderPageTooLargeError",
  { sizeBytes: Schema.Number },
) {
  override get message(): string {
    return `With its images inlined the page is ${formatMib(this.sizeBytes)}; the limit is ${formatMib(MAX_PAGE_BYTES)}. Use smaller images.`;
  }
}

export class HtmlRenderViewportHeightError extends Schema.TaggedError<HtmlRenderViewportHeightError>()(
  "HtmlRenderViewportHeightError",
  { found: Schema.String },
) {
  override get message(): string {
    return `The page uses a viewport height unit (${this.found}). The frame grows to fit the page, so a size that follows the viewport makes it grow again and again. Let content set the height, or use fixed pixel heights.`;
  }
}

// Check only stylesheets and style attributes, even inside scripts; skip comments whole.
// Consume unclosed comments, tags, or quotes through EOF to keep both patterns linear.
const CSS_SOURCE =
  /<!--[\s\S]*?(?:-->|$)|<style\b[^>]*(?:>|$)([\s\S]*?)(?:<\/style\s*>|$)|\sstyle\s*=\s*(?:"([^"]*)(?:"|$)|'([^']*)(?:'|$)|([^\s>]+))/gi;
// The lookbehind skips base64 runs, such as an inlined image that happens to contain "1vh".
const VIEWPORT_HEIGHT_UNIT = /(?<![\w.+/])(?:\d+(?:\.\d+)?|\.\d+)[sld]?vh(?![\w-])/i;

const rejectViewportHeight = (html: string) => {
  for (const [, sheet, doubleQuoted, singleQuoted, unquoted] of html.matchAll(CSS_SOURCE)) {
    const css = sheet ?? doubleQuoted ?? singleQuoted ?? unquoted ?? "";
    const found = VIEWPORT_HEIGHT_UNIT.exec(css)?.[0];
    if (found !== undefined) return Effect.fail(new HtmlRenderViewportHeightError({ found }));
  }
  return Effect.void;
};

export class HtmlRenderStoreError extends Schema.TaggedError<HtmlRenderStoreError>()(
  "HtmlRenderStoreError",
  { cause: Schema.Defect() },
) {
  override get message(): string {
    return "The HTML render could not be saved.";
  }
}

export type HtmlRenderPrepareError =
  | HtmlRenderImagesNotFoundError
  | HtmlRenderImageTooLargeError
  | HtmlRenderPageTooLargeError
  | HtmlRenderViewportHeightError;

export interface HtmlPreview {
  readonly png: string;
  readonly width: number;
  readonly contentHeight: number;
  readonly capturedHeight: number;
  readonly consoleMessages: ReadonlyArray<HeadlessChrome.ConsoleMessage>;
  readonly missingImages?: ReadonlyArray<string>;
}

export class HtmlRender extends Context.Service<
  HtmlRender,
  {
    readonly prepare: (html: string) => Effect.Effect<string, HtmlRenderPrepareError>;
    readonly publish: (input: {
      readonly threadId: ThreadId;
      readonly html: string;
      readonly title: string;
      readonly height: number;
    }) => Effect.Effect<HtmlRenderReference, HtmlRenderPrepareError | HtmlRenderStoreError>;
    readonly preview: (input: {
      readonly html: string;
      readonly width?: number | undefined;
      readonly appearance?: ThemeAppearance | undefined;
    }) => Effect.Effect<
      HtmlPreview,
      | Exclude<HtmlRenderPrepareError, HtmlRenderImagesNotFoundError>
      | PreviewBrowser.PreviewBrowserInstallError
      | PreviewBrowser.PreviewBrowserInstallingError
      | PreviewBrowser.PreviewBrowserUnsupportedError
      | PreviewBrowserHost.PreviewBrowserHostError
      | HeadlessChrome.HtmlRenderBrowserError
    >;
  }
>()("t3/htmlRender/HtmlRender") {}

const IMAGE_MIME_TYPES: Record<string, string> = {
  png: "image/png",
  jpg: "image/jpeg",
  jpeg: "image/jpeg",
  gif: "image/gif",
  webp: "image/webp",
  avif: "image/avif",
  svg: "image/svg+xml",
  bmp: "image/bmp",
  ico: "image/x-icon",
};
const IMAGE_EXTENSIONS = Object.keys(IMAGE_MIME_TYPES).join("|");
const ABSOLUTE_PATH = String.raw`(?:/(?!/)|[a-z]:[\\/])`;
const LOCAL_IMAGE_PATTERN = new RegExp(
  String.raw`(["'\x60])(${ABSOLUTE_PATH}(?:(?!\1)[^\r\n]){0,2048}?\.(?:${IMAGE_EXTENSIONS}))\1` +
    String.raw`|url\(\s*(${ABSOLUTE_PATH}[^\s"'\x60()]{0,2048}?\.(?:${IMAGE_EXTENSIONS}))\s*\)`,
  "gid",
);

const findLocalImages = (html: string) =>
  Array.from(html.matchAll(LOCAL_IMAGE_PATTERN)).flatMap((match) => {
    const span = match.indices?.[2] ?? match.indices?.[3];
    return span ? [{ start: span[0], end: span[1], path: html.slice(span[0], span[1]) }] : [];
  });

// Inside a JS string literal a Windows path's backslashes are escaped.
const filePathFor = (reference: string) =>
  /^[a-z]:/i.test(reference) ? reference.replaceAll("\\\\", "\\") : reference;

const dataUriPrefix = (path: string) =>
  `data:${IMAGE_MIME_TYPES[path.slice(path.lastIndexOf(".") + 1).toLowerCase()] ?? "application/octet-stream"};base64,`;

const latin1 = (bytes: Uint8Array, start: number, end: number) =>
  String.fromCharCode(...bytes.subarray(start, end));

// Validate bytes, not filenames, so renamed files or symlinks cannot inline secrets.
const isImageBytes = (bytes: Uint8Array) => {
  const head = latin1(bytes, 0, 12);
  if (
    head.startsWith("\x89PNG") ||
    head.startsWith("\xff\xd8\xff") ||
    head.startsWith("GIF8") ||
    head.startsWith("\0\0\x01\0") ||
    (head.startsWith("BM") && head.slice(6, 10) === "\0\0\0\0") ||
    (head.startsWith("RIFF") && head.slice(8, 12) === "WEBP") ||
    /^ftyp(?:avif|avis|mif1)$/.test(head.slice(4, 12))
  ) {
    return true;
  }
  return hasSvgRoot(new TextDecoder().decode(bytes.subarray(0, 4096)));
};

const after = (text: string, token: string, from: number) => {
  const at = text.indexOf(token, from);
  return at === -1 ? -1 : at + token.length;
};

const hasSvgRoot = (text: string) => {
  let at = 0;
  while (at !== -1) {
    while (/\s/.test(text.charAt(at))) at += 1;
    if (text.startsWith("<?", at)) at = after(text, "?>", at + 2);
    else if (text.startsWith("<!--", at)) at = after(text, "-->", at + 4);
    else if (text.slice(at, at + 9).toLowerCase() === "<!doctype") at = afterDoctype(text, at + 9);
    // XML names are case-sensitive, and only these characters can end one here.
    else return /^<svg[ \t\r\n/>]/.test(text.slice(at, at + 5));
  }
  return false;
};

const afterDoctype = (text: string, from: number) => {
  let inSubset = false;
  let at = from;
  while (at !== -1 && at < text.length) {
    const char = text[at];
    if (char === '"' || char === "'") at = after(text, char, at + 1);
    else if (inSubset && text.startsWith("<!--", at)) at = after(text, "-->", at + 4);
    else if (inSubset && text.startsWith("<?", at)) at = after(text, "?>", at + 2);
    else if (char === ">" && !inSubset) return at + 1;
    else {
      if (char === "[") inSubset = true;
      else if (char === "]") inSubset = false;
      at += 1;
    }
  }
  return -1;
};

const inlineLocalImages = Effect.fn("HtmlRender.inlineLocalImages")(function* (html: string) {
  const fileSystem = yield* FileSystem.FileSystem;
  const references = findLocalImages(html);
  const files = yield* Effect.forEach(
    [...new Set(references.map((reference) => reference.path))],
    (path) =>
      fileSystem.stat(filePathFor(path)).pipe(
        Effect.map((info) => ({
          path,
          size: info.type === "File" ? Number(info.size) : undefined,
        })),
        Effect.orElseSucceed(() => ({ path, size: undefined })),
      ),
    { concurrency: 8 },
  );
  const oversized = files.find((file) => file.size !== undefined && file.size > MAX_IMAGE_BYTES);
  if (oversized?.size !== undefined) {
    return yield* new HtmlRenderImageTooLargeError({
      path: oversized.path,
      sizeBytes: oversized.size,
    });
  }
  const sizes = new Map(files.map((file) => [file.path, file.size]));
  const pageBytes = references.reduce((total, reference) => {
    const size = sizes.get(reference.path);
    return size === undefined
      ? total
      : total +
          dataUriPrefix(reference.path).length +
          Math.ceil(size / 3) * 4 -
          Buffer.byteLength(reference.path);
  }, Buffer.byteLength(html));
  if (pageBytes > MAX_PAGE_BYTES) {
    return yield* new HtmlRenderPageTooLargeError({ sizeBytes: pageBytes });
  }
  // Files can grow after stat; bound each read and stop when accumulated images cannot fit.
  let readBytes = 0;
  const images = yield* Effect.forEach(
    files.filter((file) => file.size !== undefined),
    (file) =>
      Effect.gen(function* () {
        const read = yield* fileSystem
          .stream(filePathFor(file.path), { bytesToRead: MAX_IMAGE_BYTES + 1 })
          .pipe(Stream.mkUint8Array, Effect.option);
        if (Option.isNone(read) || !isImageBytes(read.value)) return [];
        const bytes = read.value;
        if (bytes.byteLength > MAX_IMAGE_BYTES) {
          return yield* new HtmlRenderImageTooLargeError({
            path: file.path,
            sizeBytes: bytes.byteLength,
          });
        }
        readBytes += Math.ceil(bytes.byteLength / 3) * 4;
        if (readBytes > MAX_PAGE_BYTES) {
          return yield* new HtmlRenderPageTooLargeError({ sizeBytes: readBytes });
        }
        return [{ path: file.path, bytes }];
      }),
    { concurrency: 4 },
  ).pipe(Effect.map((entries) => entries.flat()));
  const dataUris = new Map(
    images.map(
      (image) =>
        [
          image.path,
          dataUriPrefix(image.path) + Buffer.from(image.bytes).toString("base64"),
        ] as const,
    ),
  );
  const parts: Array<string> = [];
  let cursor = 0;
  for (const reference of references) {
    const dataUri = dataUris.get(reference.path);
    if (dataUri === undefined) continue;
    parts.push(html.slice(cursor, reference.start), dataUri);
    cursor = reference.end;
  }
  parts.push(html.slice(cursor));
  const inlined = parts.join("");
  const inlinedBytes = Buffer.byteLength(inlined);
  if (inlinedBytes > MAX_PAGE_BYTES) {
    return yield* new HtmlRenderPageTooLargeError({ sizeBytes: inlinedBytes });
  }
  return {
    html: inlined,
    missing: files.filter((file) => !dataUris.has(file.path)).map((file) => file.path),
  };
});

const MIN_PREVIEW_WIDTH = 240;
const MAX_PREVIEW_WIDTH = 1_600;
const MAX_CONCURRENT_BROWSERS = 2;
const MEASURE_TIMEOUT = "6 seconds";

const MEASURE_FRAGMENT = htmlRenderThemeFragment(
  htmlRenderTheme(T3_CODE_DARK_THEME_COLORS, "dark", HTML_RENDER_MEASURE_FONTS),
);

const make = Effect.gen(function* () {
  const fileSystem = yield* FileSystem.FileSystem;
  const config = yield* ServerConfig.ServerConfig;
  const previewBrowser = yield* PreviewBrowser.PreviewBrowser;
  const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
  const services = yield* Effect.context<
    FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner
  >();
  const browsers = yield* Semaphore.make(MAX_CONCURRENT_BROWSERS);
  // Keep Chrome sandboxed unless explicitly disabled; root must opt out to run.
  const noSandbox = PreviewBrowserHost.sandboxDisabled(yield* HostProcess.Environment);
  // sudo resets the environment, so the command has to name this server's home.
  const setupCommand = yield* resolveRootCliCommand(PreviewBrowserHost.SETUP_SUBCOMMAND, [
    "--base-dir",
    config.baseDir,
  ]);

  const launching = <A>(
    executable: string,
    run: (noSandbox: boolean) => Effect.Effect<A, HeadlessChrome.HtmlRenderBrowserError>,
  ) =>
    browsers.withPermits(1)(
      run(noSandbox).pipe(
        Effect.catchTags({
          HtmlRenderBrowserError: (error) =>
            error.output === undefined
              ? Effect.fail(error)
              : PreviewBrowserHost.diagnoseLaunchFailure({
                  executable,
                  setupCommand,
                  output: error.output,
                }).pipe(
                  Effect.provideContext(services),
                  Effect.flatMap((hostError) => Effect.fail(hostError ?? error)),
                ),
        }),
      ),
    );

  const measure = Effect.fn("HtmlRender.measure")(
    function* (html: string) {
      const executable = yield* previewBrowser.installed;
      if (Option.isNone(executable)) return undefined;
      const heights = yield* launching(executable.value, (noSandbox) =>
        HeadlessChrome.measureHtmlHeights({
          executable: executable.value,
          noSandbox,
          html,
          widths: HTML_RENDER_MEASURE_WIDTHS,
          urlFragment: MEASURE_FRAGMENT,
        }).pipe(Effect.provideContext(services)),
      ).pipe(
        Effect.timeoutOrElse({
          duration: MEASURE_TIMEOUT,
          orElse: () =>
            Effect.fail(
              new HeadlessChrome.HtmlRenderBrowserError({
                reason: `measuring took longer than ${MEASURE_TIMEOUT}`,
              }),
            ),
        }),
      );
      return heights.toSorted(([left], [right]) => left - right);
    },
    Effect.catch((cause) =>
      Effect.logWarning("Could not measure an HTML render; publishing it without heights.", {
        cause,
      }).pipe(Effect.as(undefined)),
    ),
  );

  // The bootstrap goes in first so its head scan never runs over inlined image data.
  const inline = (html: string) =>
    inlineLocalImages(injectHtmlRenderBootstrap(html)).pipe(Effect.provideContext(services));

  const prepare = Effect.fn("HtmlRender.prepare")(function* (html: string) {
    yield* rejectViewportHeight(html);
    const inlined = yield* inline(html);
    if (inlined.missing.length > 0) {
      return yield* new HtmlRenderImagesNotFoundError({ paths: inlined.missing });
    }
    return inlined.html;
  });

  const publish = Effect.fn("HtmlRender.publish")(function* (input: {
    readonly threadId: ThreadId;
    readonly html: string;
    readonly title: string;
    readonly height: number;
  }) {
    const html = yield* prepare(input.html);
    // The `-html` id suffix makes the asset route serve it as a sandboxed text/html document.
    const attachmentId = createAttachmentId(input.threadId, "html");
    const filePath =
      attachmentId === null
        ? null
        : resolveAttachmentRelativePath({
            attachmentsDir: config.attachmentsDir,
            relativePath: `${attachmentId}.html`,
          });
    if (attachmentId === null || filePath === null) {
      return yield* new HtmlRenderStoreError({ cause: new Error("Invalid thread id.") });
    }
    const baseReference: HtmlRenderReference = {
      attachmentId,
      title: input.title.trim().slice(0, HTML_RENDER_MAX_TITLE_LENGTH) || "HTML",
      height: clampHtmlRenderHeight(input.height),
    };
    return yield* fileSystem.writeFileString(filePath, html).pipe(
      Effect.mapError((cause) => new HtmlRenderStoreError({ cause })),
      Effect.uninterruptible,
      Effect.andThen(measure(html)),
      Effect.andThen((heights) => {
        const reference: HtmlRenderReference = {
          ...baseReference,
          ...(heights === undefined ? {} : { heights }),
        };
        return mcpSessions
          .recordHtmlRender(input.threadId, input, reference)
          .pipe(Effect.as(reference));
      }),
      // An interrupted publish must leave neither an attachment nor a recoverable reference.
      Effect.onError(() =>
        Effect.all(
          [
            fileSystem.remove(filePath, { force: true }).pipe(Effect.ignore),
            mcpSessions.takeHtmlRender(input.threadId, input, baseReference).pipe(Effect.ignore),
          ],
          { discard: true },
        ),
      ),
    );
  });

  const preview = Effect.fn("HtmlRender.preview")(function* (input: {
    readonly html: string;
    readonly width?: number | undefined;
    readonly appearance?: ThemeAppearance | undefined;
  }) {
    const width = Math.min(
      MAX_PREVIEW_WIDTH,
      Math.max(MIN_PREVIEW_WIDTH, Math.round(input.width ?? HTML_RENDER_COLUMN_WIDTH)),
    );
    const appearance = input.appearance ?? "dark";
    yield* rejectViewportHeight(input.html);
    const inlined = yield* inline(input.html);
    const executable = yield* previewBrowser.executable;
    const theme = htmlRenderTheme(
      appearance === "light" ? T3_CODE_LIGHT_THEME_COLORS : T3_CODE_DARK_THEME_COLORS,
      appearance,
      HTML_RENDER_MEASURE_FONTS,
    );
    const screenshot = yield* launching(executable, (noSandbox) =>
      HeadlessChrome.captureHtmlScreenshot({
        executable,
        noSandbox,
        html: inlined.html,
        width,
        urlFragment: htmlRenderThemeFragment(theme),
        appearance,
      }).pipe(Effect.provideContext(services)),
    );
    return {
      ...screenshot,
      width,
      ...(inlined.missing.length === 0 ? {} : { missingImages: inlined.missing }),
    } satisfies HtmlPreview;
  });

  return HtmlRender.of({ prepare, publish, preview });
});

export const layer = Layer.effect(HtmlRender, make);