@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/utils/lease-liabilities.ts

@@ -0,0 +1,54 @@
+import type { FinancialStatement } from "../types/financials";
+
+/**
+ * How net debt treats the lease liabilities a listing's balance sheets report (docs/financial-ratios.md#leases):
+ *
+ * - `included`: added to total debt. IFRS 16 puts every lessee lease on the balance sheet and reports EBITDA before
+ *   lease costs, so leverage with the leases in is like for like (IAG's June 2026 balance sheet: 6.96bn of
+ *   borrowings, 6.91bn of leases, 9.18bn of cash).
+ * - `excluded`: a company reporting under US GAAP, whatever form it files (a 10-K, or a 20-F as BABA, PDD and JD
+ *   do). Its finance leases are already in total debt and its operating lease cost is in EBITDA, so its operating
+ *   leases stay out.
+ *
+ * The standard is the one Gloom Cloud reads from the issuer's latest annual report to the SEC
+ * (`accountingStandard`), the signal its enterprise value check bridges by. Where no row states it, a row dated by
+ * a 10-K or 10-Q (`dateSource: "sec"`) is US GAAP, and a company that files none with the SEC is IFRS.
+ */
+export type LeaseBasis = "included" | "excluded";
+
+type LeaseLines = Pick<FinancialStatement, "capitalLeaseObligations" | "dateSource" | "accountingStandard">;
+
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+
+/** The listing's lease basis, or undefined when no balance sheet on file reports lease liabilities. */
+export function leaseBasis(statements: Iterable<LeaseLines>): LeaseBasis | undefined {
+  let leases = false;
+  let standard: FinancialStatement["accountingStandard"];
+  let secDated = false;
+  for (const statement of statements) {
+    if (finite(statement.capitalLeaseObligations) && statement.capitalLeaseObligations > 0) leases = true;
+    standard ??= statement.accountingStandard;
+    if (statement.dateSource === "sec") secDated = true;
+  }
+  if (!leases) return undefined;
+  return (standard ? standard === "us-gaap" : secDated) ? "excluded" : "included";
+}
+
+/** Amounts are whole units; some providers round a leg to the thousand. */
+const close = (a: number, b: number) => Math.abs(a - b) <= Math.max(1_000, Math.abs(a) * 1e-6);
+
+/**
+ * A balance sheet's total debt and lease liabilities. A total that already holds the lease line (long-term and
+ * current debt plus leases) is read as the borrowings beside it, so the leases count once. Undefined without both
+ * lines: a missing lease line is never zero.
+ */
+export function debtAndLeases(
+  statement: Pick<FinancialStatement, "totalDebt" | "capitalLeaseObligations" | "longTermDebt" | "currentDebt">,
+): { totalDebt: number; leases: number } | undefined {
+  const total = statement.totalDebt;
+  const leases = statement.capitalLeaseObligations;
+  if (!finite(total) || !finite(leases) || leases < 0) return undefined;
+  const { longTermDebt: long, currentDebt: current } = statement;
+  const holds = leases > 0 && (finite(long) || finite(current)) && close(total, (long ?? 0) + (current ?? 0) + leases);
+  return { totalDebt: holds ? total - leases : total, leases };
+}

package/src/utils/main-thread-stall.ts

@@ -1,4 +1,4 @@
-import { lastPerfSample, recordPerfSample } from "./perf-marks";
+import { lastPerfSample, recordPerfSample, withoutLastStep } from "./perf-marks";
 
 /** How often the monitor checks in. Short enough to date a stall precisely. */
 const SAMPLE_INTERVAL_MS = 250;
@@ -9,15 +9,54 @@ const SAMPLE_INTERVAL_MS = 250;
  */
 const STALL_THRESHOLD_MS = 400;
 
+/** The facts a `sqlite.blocked` step was measured with (data/sqlite/retry.ts). */
+interface StallSqliteDetail {
+  /** The statement's fixed name, such as "touch cached resource". */
+  operation: string;
+  attempts: number;
+  /** Whether it waited on another connection's lock, rather than being slow on its own. */
+  lockWait: boolean;
+}
+
+/**
+ * What a platform's own clocks say at one instant (telemetry/stall-clocks.ts),
+ * in ms from any origin. Null where the platform cannot say.
+ */
+export interface StallClockReading {
+  /** Time the computer was awake: sleep and suspend do not count. */
+  awakeMs: number | null;
+  /** CPU time this thread has used. */
+  threadCpuMs: number | null;
+  /** CPU time the whole process has used, every thread together. */
+  processCpuMs: number | null;
+}
+
 export interface StallEvent {
+  /** How long the thread could not run while the computer was awake. */
   blockedMs: number;
   /** The last measured section before the stall (perf-marks), if any. */
   lastMeasured?: string;
   /** How long before the stall was noticed that section ended. */
   lastMeasuredEndedMsAgo?: number;
+  /** When that section was a SQLite statement that held the thread. */
+  sqlite?: StallSqliteDetail;
+  /** How long the process had been running when the stall was noticed. */
+  uptimeMs?: number;
+  /** Whether the process had finished starting (`markStartupComplete`). */
+  phase?: "startup" | "steady";
+  /**
+   * Share of the stall the thread spent on the CPU, 0 to 1: near 1 it was
+   * busy (script, a collection), near 0 it waited (the disk, a lock, a
+   * native call answered on another thread).
+   */
+  threadCpu?: number;
+  /** CPU the process's other threads used meanwhile, in cores (1: one core throughout). */
+  otherCpu?: number;
 }
 
 let stallSink: ((event: StallEvent) => void) | null = null;
+let stallClocks: (() => StallClockReading) | null = null;
+let startupComplete = false;
 
 /**
  * Where this process's stalls go besides the Debug Log: the stall log and its
@@ -31,14 +70,62 @@ export function setStallSink(next: ((event: StallEvent) => void) | null): () =>
   };
 }
 
+/**
+ * How this process reads its platform's clocks (telemetry/stall-clocks.ts):
+ * a stall then says whether the thread was busy or waiting, and the time
+ * the computer slept is not counted as one.
+ */
+export function setStallClocks(next: (() => StallClockReading) | null): () => void {
+  stallClocks = next;
+  return () => {
+    if (stallClocks === next) stallClocks = null;
+  };
+}
+
+function readStallClocks(read: (() => StallClockReading) | null): StallClockReading | null {
+  if (!read) return null;
+  try {
+    return read();
+  } catch {
+    // Intentional ignore: a clock that cannot be read leaves the stall's cause unknown, never the stall unseen.
+    return null;
+  }
+}
+
+function delta(after: number | null | undefined, before: number | null | undefined): number | null {
+  return after == null || before == null ? null : after - before;
+}
+
+/**
+ * The process is up: its first screen has its data, or (the desktop app's
+ * Bun process) the main window has what it asked for. Stalls before this are
+ * reported as startup ones.
+ */
+export function markStartupComplete(): void {
+  startupComplete = true;
+}
+
+/** Test seam. */
+export function resetStartupCompleteForTests(): void {
+  startupComplete = false;
+}
+
 function noteStall(event: StallEvent): void {
   try {
-    stallSink?.(event);
+    withoutLastStep(() => stallSink?.(event));
   } catch {
     // Intentional ignore: reporting a freeze must never become one.
   }
 }
 
+/** The facts of a `sqlite.blocked` sample, when they have the shape retry.ts gives them. */
+function sqliteDetail(metadata: Record<string, unknown> | undefined): StallSqliteDetail | undefined {
+  if (!metadata) return undefined;
+  const { operation, attempts, lockWait } = metadata;
+  if (typeof operation !== "string" || typeof attempts !== "number") return undefined;
+  return { operation, attempts, lockWait: lockWait === true };
+}
+
 export interface MainThreadStallMonitorOptions {
   intervalMs?: number;
   thresholdMs?: number;
@@ -46,6 +133,8 @@ export interface MainThreadStallMonitorOptions {
   schedule?: (callback: () => void, delayMs: number) => unknown;
   cancel?: (handle: unknown) => void;
   report?: (blockedMs: number, context: Omit<StallEvent, "blockedMs">) => void;
+  /** Defaults to the clocks `setStallClocks` installed. */
+  clocks?: () => StallClockReading;
 }
 
 function defaultNow(): number {
@@ -60,7 +149,15 @@ function defaultNow(): number {
  * comes back late, the app was unresponsive for exactly that long. The report
  * carries the last measured section and how long before the stall it ended,
  * which is usually enough to tell "the cache read did it" from "the render
- * did it" in a report that only says the app hung for a few seconds.
+ * did it" in a report that only says the app hung for a few seconds, and how
+ * long the process had been up, so a slow start reads apart from a hang
+ * hours in.
+ *
+ * Where the platform's clocks can be read, the time the computer slept is
+ * taken out (a timer cannot fire then either, and a laptop's lid is not a
+ * freeze), and the stall says how much of it the thread spent on the CPU
+ * and how busy the process's other threads were: busy is script or a
+ * collection, idle on both is a wait on the disk or another program.
  */
 export function startMainThreadStallMonitor(
   options: MainThreadStallMonitorOptions = {},
@@ -72,21 +169,41 @@ export function startMainThreadStallMonitor(
   const cancel = options.cancel ?? ((handle) => clearInterval(handle as ReturnType<typeof setInterval>));
   const report = options.report
     ?? ((blockedMs, context) => {
-      recordPerfSample("runtime.stall", blockedMs, context);
+      // Logged, but not a step: the next stall still names the work before it.
+      recordPerfSample("runtime.stall", blockedMs, context, { lastStep: false });
       noteStall({ blockedMs, ...context });
     });
 
+  const clocks = () => readStallClocks(options.clocks ?? stallClocks);
   let previous = now();
+  let previousClocks = clocks();
   const handle = schedule(() => {
     const current = now();
-    const blockedMs = current - previous - intervalMs;
+    const currentClocks = clocks();
+    const elapsedMs = current - previous;
+    const before = previousClocks;
     previous = current;
+    previousClocks = currentClocks;
+    const awakeMs = delta(currentClocks?.awakeMs, before?.awakeMs);
+    // Asleep, the computer runs nothing; only the awake part of the gap was a freeze.
+    const asleepMs = awakeMs == null ? 0 : Math.max(0, elapsedMs - awakeMs);
+    const blockedMs = elapsedMs - asleepMs - intervalMs;
     if (blockedMs < thresholdMs) return;
     const sample = lastPerfSample();
+    const sqlite = sample?.name === "sqlite.blocked" ? sqliteDetail(sample.metadata) : undefined;
+    const threadCpuMs = delta(currentClocks?.threadCpuMs, before?.threadCpuMs);
+    const processCpuMs = delta(currentClocks?.processCpuMs, before?.processCpuMs);
     report(blockedMs, {
       ...(sample
         ? { lastMeasured: sample.name, lastMeasuredEndedMsAgo: Math.round(current - sample.endedAt) }
         : {}),
+      ...(sqlite ? { sqlite } : {}),
+      uptimeMs: Math.round(current),
+      phase: startupComplete ? "steady" : "startup",
+      ...(threadCpuMs == null ? {} : { threadCpu: Math.min(1, Math.max(0, threadCpuMs / blockedMs)) }),
+      ...(threadCpuMs == null || processCpuMs == null
+        ? {}
+        : { otherCpu: Math.max(0, (processCpuMs - threadCpuMs) / (elapsedMs - asleepMs)) }),
     });
   }, intervalMs);
   if (handle && typeof (handle as { unref?: () => void }).unref === "function") {

package/src/utils/perf-marks.ts

@@ -20,27 +20,50 @@ function now(): number {
     : Date.now();
 }
 
-// Two scalars rather than an object: every measured section writes them, and
-// only the stall monitor ever reads them.
+// Scalars rather than an object: every measured section writes them, and
+// only the stall monitor ever reads them. The metadata is the caller's own
+// object, kept by reference.
 let lastSampleName: string | null = null;
 let lastSampleEndedAt = 0;
+let lastSampleDurationMs = 0;
+let lastSampleMetadata: Record<string, unknown> | undefined;
+/** Inside `withoutLastStep`: samples are logged, and none becomes the last step. */
+let quietDepth = 0;
 
 /**
- * The most recent measured section and when it ended. The stall monitor reads
- * it so a report of "the app froze" carries the last thing the app is known to
- * have been doing.
+ * The most recent measured section, when it ended and what it was measured
+ * with. The stall monitor reads it so a report of "the app froze" carries the
+ * last thing the app is known to have been doing.
  */
-export function lastPerfSample(): { name: string; endedAt: number } | null {
-  return lastSampleName == null ? null : { name: lastSampleName, endedAt: lastSampleEndedAt };
+export function lastPerfSample(): { name: string; endedAt: number; metadata?: Record<string, unknown> } | null {
+  if (lastSampleName == null) return null;
+  return { name: lastSampleName, endedAt: lastSampleEndedAt, ...(lastSampleMetadata ? { metadata: lastSampleMetadata } : {}) };
+}
+
+/**
+ * Whether the last step ended inside a section that started at `startedAt`
+ * and took at least half of its `durationMs`. That step says more about the
+ * time than the section around it: a SQLite statement that held the thread
+ * through most of a window's request keeps its lock and try facts, where a
+ * short one before the request's real work does not.
+ */
+function lastStepAccountsForSection(startedAt: number, durationMs: number): boolean {
+  return lastSampleName != null && lastSampleEndedAt >= startedAt && lastSampleDurationMs * 2 >= durationMs;
 }
 
 function logSlowPerfSample(
   name: string,
   durationMs: number,
   metadata?: Record<string, unknown>,
+  lastStep = true,
+  startedAt?: number,
 ): void {
-  lastSampleName = name;
-  lastSampleEndedAt = now();
+  if (lastStep && quietDepth === 0 && (startedAt === undefined || !lastStepAccountsForSection(startedAt, durationMs))) {
+    lastSampleName = name;
+    lastSampleEndedAt = now();
+    lastSampleDurationMs = durationMs;
+    lastSampleMetadata = metadata;
+  }
   const payload = {
     durationMs: Math.round(durationMs * 10) / 10,
     ...(metadata ?? {}),
@@ -56,19 +79,42 @@ function logSlowPerfSample(
   }
 }
 
+/**
+ * Runs `fn` without any section it measures becoming the step a later stall
+ * names: reporting a stall reads the windows, and the next stall must still
+ * name the work before it, not the report.
+ */
+export function withoutLastStep<T>(fn: () => T): T {
+  quietDepth += 1;
+  try {
+    return fn();
+  } finally {
+    quietDepth -= 1;
+  }
+}
+
 export function isPerfTraceEnabled(): boolean {
   return traceToStderr;
 }
 
-/** A sample measured elsewhere (a React Profiler callback, for instance). */
+/**
+ * A sample measured elsewhere (a React Profiler callback, for instance).
+ * `lastStep: false` logs it without making it the step a later stall names:
+ * the stall monitor's own samples, which measure no work.
+ */
 export function recordPerfSample(
   name: string,
   durationMs: number,
   metadata?: Record<string, unknown>,
+  options?: { lastStep?: boolean },
 ): void {
-  logSlowPerfSample(name, durationMs, metadata);
+  logSlowPerfSample(name, durationMs, metadata, options?.lastStep !== false);
 }
 
+/**
+ * Measures `fn`. A step measured inside it that took most of its time stays
+ * the step a stall names (`lastStepAccountsForSection`).
+ */
 export function measurePerf<T>(
   name: string,
   fn: () => T,
@@ -78,7 +124,7 @@ export function measurePerf<T>(
   try {
     return fn();
   } finally {
-    logSlowPerfSample(name, now() - start, metadata);
+    logSlowPerfSample(name, now() - start, metadata, true, start);
   }
 }
 

package/src/utils/price-history-integrity.ts

@@ -46,6 +46,50 @@ export function pricePointIntegrityFlags(point: PricePoint): string[] {
   return flags;
 }
 
+/**
+ * A wick too far from its bar's body to have traded: a low under half the lower
+ * of open and close, or a high over twice the higher, as `low<close/2` or
+ * `high>2*open` (IAG on LSE, 2021-11-29: a low of 0.0155 under a close of
+ * 1.316). Only that wick is withheld: the open and close stand, so closes,
+ * returns and drawdowns read the bar while lows, highs and ranges do not.
+ * Empty when the wicks are plausible, or when the bar's prices contradict
+ * each other, which blanks it whole (pricePointIntegrityFlags).
+ */
+export function pricePointWickFlags(point: PricePoint): string[] {
+  const { open, high, low, close } = point;
+  if (pricePointIntegrityFlags(point).length > 0) return [];
+  const body = [["open", open], ["close", close]].filter((entry): entry is [string, number] => isFiniteNumber(entry[1]));
+  if (body.length === 0) return [];
+  // On a tie the close names the side, as the price the bar is read by.
+  const [bottomName, bottom] = body.reduce((least, entry) => entry[1] <= least[1] ? entry : least);
+  const [topName, top] = body.reduce((most, entry) => entry[1] >= most[1] ? entry : most);
+  const flags: string[] = [];
+  if (isFiniteNumber(low) && bottom > 0 && low < bottom / 2) flags.push(`low<${bottomName}/2`);
+  if (isFiniteNumber(high) && top > 0 && high > top * 2) flags.push(`high>2*${topName}`);
+  return flags;
+}
+
+/** Whether a flag code is a withheld wick (pricePointWickFlags), whose bar keeps its open and close. */
+export function isWickFlag(code: string): boolean {
+  return /^(low<(open|close)\/2|high>2\*(open|close))$/.test(code);
+}
+
+/** A bar's high and low with a wick too far from its body to have traded (pricePointWickFlags) left out. */
+export function pricePointWicks(point: PricePoint): { high: number | undefined; low: number | undefined } {
+  const flags = pricePointWickFlags(point);
+  return {
+    high: flags.some((flag) => flag.startsWith("high")) ? undefined : point.high,
+    low: flags.some((flag) => flag.startsWith("low")) ? undefined : point.low,
+  };
+}
+
+/** "1 bar has a low or high too far from its open and close to have traded; left out of ranges.", or undefined for none. */
+export function priceHistoryWickNotice(count: number): string | undefined {
+  return count > 0
+    ? `${count === 1 ? "1 bar has a low or high" : `${count} bars have lows or highs`} too far from ${count === 1 ? "its" : "their"} open and close to have traded; left out of ranges.`
+    : undefined;
+}
+
 export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity | undefined {
   if (pricePointIntegrityFlags(point).length === 0) return undefined;
   const date = new Date(point.date);
@@ -58,8 +102,10 @@ export function pricePointIntegrity(point: PricePoint): PriceHistoryIntegrity |
 /** Calculation/display fields deliberately exclude the contradictory source row. */
 export function pricePointValues(point: PricePoint, integrity = pricePointIntegrity(point)) {
   const value = (number: number | undefined) => !integrity && isFiniteNumber(number) ? number : null;
+  // A wick too far from the body to have traded is left out; the rest of the bar stands.
+  const wicks = pricePointWicks(point);
   return {
-    open: value(point.open), high: value(point.high), low: value(point.low),
+    open: value(point.open), high: value(wicks.high), low: value(wicks.low),
     close: value(point.close), volume: value(point.volume),
     ...(integrity ? { integrity } : {}),
   };

package/src/utils/private-files.ts

@@ -0,0 +1,141 @@
+import { chmodSync, closeSync, constants, fchmodSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, writeSync } from "fs";
+import { chmod, lstat, mkdir, open } from "fs/promises";
+
+/**
+ * The profile keeps broker credentials (config.json), the Cloud session (the
+ * database), a remote-control token and logs of what the user looked at. On
+ * POSIX its folders are opened only by the user and its files read only by
+ * them, whatever the umask. Windows keeps the profile under the user's own
+ * folder, whose access list already does this, and has no such modes: there
+ * every call here only creates and writes.
+ */
+const PRIVATE_DIR_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+
+function usesPosixModes(): boolean {
+  return process.platform !== "win32";
+}
+
+function errorCode(error: unknown): unknown {
+  return (error as { code?: unknown } | null)?.code;
+}
+
+/** Creates `path` and the folders above it as `mkdir -p` does, each one it creates open to the user alone. */
+export function makePrivateDirSync(path: string): void {
+  mkdirSync(path, { recursive: true, mode: PRIVATE_DIR_MODE });
+}
+
+export async function makePrivateDir(path: string): Promise<void> {
+  await mkdir(path, { recursive: true, mode: PRIVATE_DIR_MODE });
+}
+
+/** Leaves an existing folder open to the user alone; a missing one stays missing. */
+export async function restrictDir(path: string): Promise<void> {
+  if (!usesPosixModes()) return;
+  try {
+    await chmod(path, PRIVATE_DIR_MODE);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/** Leaves an existing file readable by the user alone; a missing one stays missing. */
+export async function restrictFile(path: string): Promise<void> {
+  if (!usesPosixModes()) return;
+  try {
+    await chmod(path, PRIVATE_FILE_MODE);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+export function restrictFileSync(path: string): void {
+  if (!usesPosixModes()) return;
+  try {
+    chmodSync(path, PRIVATE_FILE_MODE);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/** The code of the error a private write throws when its path names a device, a pipe or anything else but a plain file. */
+export const NOT_A_PLAIN_FILE = "ENOTPLAINFILE";
+
+function notAPlainFile(path: string): Error {
+  return Object.assign(new Error(`${path} is not a plain file.`), { code: NOT_A_PLAIN_FILE });
+}
+
+function isALink(path: string): Error {
+  return Object.assign(new Error(`${path} is a link.`), { code: "ELOOP" });
+}
+
+/**
+ * Opened to write without following a link (`O_NOFOLLOW`, which fails with
+ * ELOOP) or waiting on a pipe no one reads (`O_NONBLOCK`). Windows has
+ * neither flag; a link is refused there by looking first.
+ */
+function privateOpenFlags(append: boolean): number {
+  return constants.O_WRONLY | constants.O_CREAT | (append ? constants.O_APPEND : 0)
+    | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+}
+
+function refuseWindowsLinkSync(path: string): void {
+  if (usesPosixModes()) return;
+  try {
+    if (lstatSync(path).isSymbolicLink()) throw isALink(path);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+async function refuseWindowsLink(path: string): Promise<void> {
+  if (usesPosixModes()) return;
+  try {
+    if ((await lstat(path)).isSymbolicLink()) throw isALink(path);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/**
+ * Writes `contents` to a plain file only the user can read: created so, and
+ * an existing file made so before anything is written to it, so the new
+ * contents are never readable by anyone else. A link, a device or a pipe in
+ * its place is refused, never written through. `append` adds to the end.
+ */
+export function writePrivateFileSync(path: string, contents: string | Uint8Array, options: { append?: boolean } = {}): void {
+  refuseWindowsLinkSync(path);
+  const fd = openSync(path, privateOpenFlags(options.append === true), PRIVATE_FILE_MODE);
+  try {
+    if (!fstatSync(fd).isFile()) throw notAPlainFile(path);
+    if (usesPosixModes()) {
+      try {
+        fchmodSync(fd, PRIVATE_FILE_MODE);
+      } catch {
+        // Intentional ignore: a disk without POSIX modes (FAT, some network shares) cannot restrict the file; the write still goes through.
+      }
+    }
+    if (!options.append) ftruncateSync(fd, 0);
+    const bytes = typeof contents === "string" ? Buffer.from(contents, "utf-8") : contents;
+    for (let written = 0; written < bytes.length;) written += writeSync(fd, bytes, written);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export async function writePrivateFile(path: string, contents: string | Uint8Array): Promise<void> {
+  await refuseWindowsLink(path);
+  const handle = await open(path, privateOpenFlags(false), PRIVATE_FILE_MODE);
+  try {
+    if (!(await handle.stat()).isFile()) throw notAPlainFile(path);
+    if (usesPosixModes()) {
+      await handle.chmod(PRIVATE_FILE_MODE).catch(() => {
+        // Intentional ignore: a disk without POSIX modes (FAT, some network shares) cannot restrict the file; the write still goes through.
+      });
+    }
+    await handle.truncate(0);
+    await handle.writeFile(contents);
+  } finally {
+    await handle.close();
+  }
+}

package/src/utils/public-address.ts

@@ -0,0 +1,99 @@
+import { isIP } from "net";
+
+/**
+ * Whether an IP address is on the public internet: not this machine, not a
+ * private or link-local network, not a carrier-grade NAT (a VPN's own
+ * addresses), documentation, multicast or reserved block. A request made for
+ * a page that only reads public data (the pane screenshot's HTTP bridge) is
+ * refused for anything else, so a URL it is handed cannot reach a service on
+ * the user's machine or network.
+ */
+export function isPublicAddress(address: string): boolean {
+  const bare = address.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+  const family = isIP(bare);
+  if (family === 4) return isPublicIpv4(parseIpv4(bare)!);
+  if (family === 6) {
+    const groups = parseIpv6(bare);
+    return groups !== null && isPublicIpv6(groups);
+  }
+  return false;
+}
+
+function parseIpv4(address: string): number[] | null {
+  const parts = address.split(".").map(Number);
+  return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) ? parts : null;
+}
+
+/** [first octet, second octet, prefix bits of the second octet that count] per non-public block. */
+const IPV4_BLOCKS: ReadonlyArray<readonly [number, number, number]> = [
+  [0, 0, 0], // 0.0.0.0/8, this network
+  [10, 0, 0], // 10.0.0.0/8, private
+  [100, 64, 2], // 100.64.0.0/10, carrier-grade NAT
+  [127, 0, 0], // 127.0.0.0/8, loopback
+  [169, 254, 8], // 169.254.0.0/16, link-local
+  [172, 16, 4], // 172.16.0.0/12, private
+  [192, 168, 8], // 192.168.0.0/16, private
+  // 198.18.0.0/15 (benchmarking) stays public: proxies that answer every name with a stand-in address use it.
+];
+
+function isPublicIpv4([a, b, c]: number[]): boolean {
+  for (const [first, second, bits] of IPV4_BLOCKS) {
+    if (a !== first) continue;
+    if (bits === 0) return false;
+    const mask = (0xff << (8 - bits)) & 0xff;
+    if ((b! & mask) === second) return false;
+  }
+  // 192.0.0.0/24 protocol assignments, 192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24 documentation.
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return false;
+  if (a === 198 && b === 51 && c === 100) return false;
+  if (a === 203 && b === 0 && c === 113) return false;
+  // 224.0.0.0/4 multicast, 240.0.0.0/4 reserved and the broadcast address.
+  return a! < 224;
+}
+
+/** Eight 16-bit groups, or null when the text is not one IPv6 address. */
+function parseIpv6(address: string): number[] | null {
+  let text = address.toLowerCase();
+  const tail: number[] = [];
+  const dotted = /:(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+  if (dotted) {
+    const v4 = parseIpv4(dotted[1]!);
+    if (!v4) return null;
+    tail.push((v4[0]! << 8) | v4[1]!, (v4[2]! << 8) | v4[3]!);
+    // `::1.2.3.4` keeps its `::`; `1:2:3:4:5:6:1.2.3.4` loses the colon before the dotted part.
+    const before = text.slice(0, dotted.index);
+    text = before.endsWith(":") ? `${before}:` : before;
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+  const read = (half: string) => (half ? half.split(":").map((group) => Number.parseInt(group, 16)) : []);
+  const head = read(halves[0]!);
+  const rest = halves.length === 2 ? read(halves[1]!) : [];
+  const known = head.length + rest.length + tail.length;
+  if (halves.length === 1 && known !== 8) return null;
+  if (halves.length === 2 && known > 7) return null;
+  const groups = [...head, ...Array(8 - known).fill(0), ...rest, ...tail];
+  return groups.every((group) => Number.isInteger(group) && group >= 0 && group <= 0xffff) ? groups : null;
+}
+
+function embeddedIpv4(high: number, low: number): number[] {
+  return [high >> 8, high & 0xff, low >> 8, low & 0xff];
+}
+
+function isPublicIpv6(groups: number[]): boolean {
+  const [g0, g1, g2, g3, g4, g5, g6, g7] = groups as [number, number, number, number, number, number, number, number];
+  // ::ffff:a.b.c.d, an IPv4 address written as IPv6: as public as the address it carries.
+  if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0xffff) return isPublicIpv4(embeddedIpv4(g6, g7));
+  // ::, ::1 and the retired IPv4-compatible block.
+  if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) return false;
+  // 64:ff9b::/96 NAT64 carries an IPv4 address; 64:ff9b:1::/48 is a local NAT64.
+  if (g0 === 0x64 && g1 === 0xff9b) return g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0 && isPublicIpv4(embeddedIpv4(g6, g7));
+  // 2002::/16 6to4 carries an IPv4 address in its next 32 bits.
+  if (g0 === 0x2002) return isPublicIpv4(embeddedIpv4(g1, g2));
+  // 100::/64 discard.
+  if (g0 === 0x100 && g1 === 0 && g2 === 0 && g3 === 0) return false;
+  // 2001::/23 protocol assignments (Teredo among them) and 2001:db8::/32 documentation.
+  if (g0 === 0x2001 && (g1 < 0x200 || g1 === 0xdb8)) return false;
+  // fc00::/7 unique local, fe80::/10 link-local, fec0::/10 site-local, ff00::/8 multicast.
+  return (g0 & 0xfe00) !== 0xfc00 && (g0 & 0xffc0) !== 0xfe80 && (g0 & 0xffc0) !== 0xfec0 && (g0 & 0xff00) !== 0xff00;
+}