@sixb/core 0.1.19 → 0.1.21

package/src/artifacts/frames/protocol.ts

@@ -0,0 +1,174 @@
+import { ARTIFACT_LIMITS } from "../limits"
+import { ARTIFACT_THEME_TOKENS } from "../theme"
+
+/**
+ * Messages between the app and a deck in its sandboxed frame. The app asks; the frame answers
+ * each request by its id, and tells the app what happened inside it as events. Later abilities
+ * are new methods and events, not a new protocol.
+ */
+export const FRAME_PROTOCOL = "sixb-frame/1"
+
+/**
+ * A deck shows one slide scaled to fit on its stage, every slide in a grid, or one slide filling
+ * the page to present it.
+ */
+export type DeckMode = "slide" | "overview" | "present"
+
+/**
+ * How a frame opens, set in its URL so the first paint is right: at a slide, and with `fill`, that
+ * slide alone filling the frame with no stage around it, as a thumbnail or an embed shows it.
+ */
+export interface FrameStart {
+  readonly slide?: number
+  readonly fill?: boolean
+}
+
+/** The fragment that carries a frame's start: `#sixb-slide=3&sixb-fill`. */
+export function frameStartHash(start: FrameStart): string {
+  const params: string[] = []
+  if (start.slide !== undefined && start.slide > 1)
+    params.push(`sixb-slide=${Math.round(start.slide)}`)
+  if (start.fill) params.push("sixb-fill")
+  return params.length > 0 ? `#${params.join("&")}` : ""
+}
+
+/** What the app asks of the frame. */
+export type FrameRequest =
+  | FrameRequestOf<
+      "theme",
+      { readonly tokens: Readonly<Record<string, string>>; readonly dark: boolean }
+    >
+  | FrameRequestOf<"goto", { readonly slide: number }>
+  | FrameRequestOf<"mode", { readonly mode: DeckMode }>
+
+interface FrameRequestOf<Method extends string, Params> {
+  readonly protocol: typeof FRAME_PROTOCOL
+  readonly id: number
+  readonly method: Method
+  readonly params: Params
+}
+
+/** The frame's answer to one request. */
+export interface FrameResponse {
+  readonly protocol: typeof FRAME_PROTOCOL
+  readonly id: number
+  readonly error?: string
+}
+
+/** What happened inside the frame. */
+export type FrameEvent =
+  | FrameEventOf<"ready", { readonly slides: number }>
+  /** The reader picked a slide in the overview. */
+  | FrameEventOf<"select", { readonly slide: number }>
+  /** A key the app handles, pressed while the frame had focus. */
+  | FrameEventOf<"key", { readonly key: string }>
+  /** A link to another artifact, which opens where the reader is. */
+  | FrameEventOf<"open", { readonly address: string }>
+  /**
+   * Where the shown slide's `<sixb-embed>` boxes are, for the app to draw each over the frame: in
+   * the frame's pixels, with the scale the slide is drawn at. Empty in the overview, where an
+   * embed stays a placeholder, as it does in a filled frame, which never reports.
+   */
+  | FrameEventOf<"embeds", { readonly embeds: readonly FrameEmbed[] }>
+
+/** One `<sixb-embed>` on the shown slide. */
+export interface FrameEmbed {
+  readonly address: string
+  readonly rect: {
+    readonly x: number
+    readonly y: number
+    readonly width: number
+    readonly height: number
+  }
+  /** The slide's scale: the embed is drawn at `rect / scale`, then scaled with the slide. */
+  readonly scale: number
+}
+
+interface FrameEventOf<Event extends string, Params> {
+  readonly protocol: typeof FRAME_PROTOCOL
+  readonly event: Event
+  readonly params: Params
+}
+
+/** Keys the frame passes to the app, so a deck navigates the same with focus in it or not. */
+export const DECK_KEYS = [
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "ArrowDown",
+  "PageUp",
+  "PageDown",
+  "Home",
+  "End",
+  " ",
+  "Escape",
+] as const
+
+/**
+ * The theme tokens the app sends into a frame, read from the viewer as it is themed: the ones an
+ * artifact's theme may set.
+ */
+export const FRAME_THEME_TOKENS = ARTIFACT_THEME_TOKENS
+
+/**
+ * A message from a frame as an event, or null when it is not one this protocol sends. A deck runs
+ * its own scripts, so anything it posts is checked for the shape the app relies on: whole slide
+ * numbers, a key the app handles, finite boxes, and no more embeds than a version may record.
+ */
+export function parseFrameEvent(data: unknown): FrameEvent | null {
+  if (!isRecord(data) || data.protocol !== FRAME_PROTOCOL || !isRecord(data.params)) return null
+  const { params } = data
+  switch (data.event) {
+    case "ready":
+      return isCount(params.slides) ? event("ready", { slides: params.slides }) : null
+    case "select":
+      return isCount(params.slide) && params.slide > 0
+        ? event("select", { slide: params.slide })
+        : null
+    case "key":
+      return typeof params.key === "string" && (DECK_KEYS as readonly string[]).includes(params.key)
+        ? event("key", { key: params.key })
+        : null
+    case "open":
+      return isAddress(params.address) ? event("open", { address: params.address }) : null
+    case "embeds": {
+      const { embeds } = params
+      if (!Array.isArray(embeds) || embeds.length > ARTIFACT_LIMITS.maxReferences) return null
+      const parsed: FrameEmbed[] = []
+      for (const embed of embeds) {
+        if (!isRecord(embed) || !isAddress(embed.address) || !isRecord(embed.rect)) return null
+        const { x, y, width, height } = embed.rect
+        if (![x, y, width, height, embed.scale].every(Number.isFinite)) return null
+        if (Number(width) < 0 || Number(height) < 0 || Number(embed.scale) <= 0) return null
+        parsed.push({
+          address: embed.address,
+          rect: { x: Number(x), y: Number(y), width: Number(width), height: Number(height) },
+          scale: Number(embed.scale),
+        })
+      }
+      return event("embeds", { embeds: parsed })
+    }
+    default:
+      return null
+  }
+}
+
+function event<Name extends FrameEvent["event"]>(
+  name: Name,
+  params: Extract<FrameEvent, { event: Name }>["params"]
+): FrameEvent {
+  return { protocol: FRAME_PROTOCOL, event: name, params } as FrameEvent
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}
+
+function isCount(value: unknown): value is number {
+  return Number.isSafeInteger(value) && Number(value) >= 0
+}
+
+/** Long enough for any address a version can record; the app resolves it before using it. */
+function isAddress(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 2048
+}

package/src/artifacts/frames/runtime.ts

@@ -0,0 +1,213 @@
+/**
+ * The runtime the frame injects into a deck before anything else in its `<head>`. It is served as
+ * this function's own source, `(${frameRuntime})()`, so it imports nothing and names nothing
+ * outside itself: the protocol string and the keys repeat what `protocol.ts` declares, and a test
+ * holds the two together.
+ *
+ * It lays the deck out: every `section.slide` is a 1280×720 slide, shown one at a time scaled to
+ * fit, or all at once in a grid. The URL's fragment can open it at a slide, and with `sixb-fill`
+ * show that slide alone filling the frame, as a thumbnail or an embed does. It applies the theme the app sends, answers the app's requests,
+ * and tells the app about keys, picks in the overview, and links to other artifacts.
+ */
+export function frameRuntime(): void {
+  const PROTOCOL = "sixb-frame/1"
+  const WIDTH = 1280
+  const HEIGHT = 720
+  const KEYS = [
+    "ArrowLeft",
+    "ArrowRight",
+    "ArrowUp",
+    "ArrowDown",
+    "PageUp",
+    "PageDown",
+    "Home",
+    "End",
+    " ",
+    "Escape",
+  ]
+  const root = document.documentElement
+  const start = new URLSearchParams(window.location.hash.slice(1))
+  root.classList.add("sixb-deck")
+  root.dataset.mode = start.has("sixb-fill") ? "fill" : "slide"
+  let current = Number(start.get("sixb-slide")) || 1
+
+  const slides = (): HTMLElement[] =>
+    Array.from(document.querySelectorAll<HTMLElement>("section.slide"))
+  const post = (message: Record<string, unknown>) =>
+    window.parent.postMessage({ protocol: PROTOCOL, ...message }, "*")
+
+  /** The scale that fits a slide in the window, and the one that fits a column of the grid. */
+  const fit = () => {
+    const columns = window.innerWidth < 720 ? 2 : window.innerWidth < 1100 ? 3 : 4
+    const gap = 16
+    // A slide keeps a margin around it, so its edge reads against the stage; filled or presented,
+    // it has none.
+    const margin =
+      root.dataset.mode === "fill" || root.dataset.mode === "present"
+        ? 0
+        : Math.min(32, window.innerWidth * 0.04)
+    root.style.setProperty(
+      "--sixb-scale",
+      String(
+        Math.min(
+          (window.innerWidth - margin * 2) / WIDTH,
+          (window.innerHeight - margin * 2) / HEIGHT
+        )
+      )
+    )
+    root.style.setProperty("--sixb-columns", String(columns))
+    root.style.setProperty(
+      "--sixb-overview-scale",
+      String((window.innerWidth - gap * (columns + 1)) / columns / WIDTH)
+    )
+  }
+
+  /** The shown slide's embeds, for the app to draw over the frame; once a frame, when they move. */
+  let reported = ""
+  let reporting = false
+  const reportEmbeds = () => {
+    if (reporting || root.dataset.mode === "fill") return
+    reporting = true
+    requestAnimationFrame(() => {
+      reporting = false
+      const scale = Number(root.style.getPropertyValue("--sixb-scale")) || 1
+      const slide = root.dataset.mode === "overview" ? undefined : slides()[current - 1]
+      const embeds = Array.from(slide?.querySelectorAll("sixb-embed[src]") ?? []).map((element) => {
+        const rect = element.getBoundingClientRect()
+        return {
+          address: (element.getAttribute("src") ?? "").trim(),
+          rect: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
+          scale,
+        }
+      })
+      const next = JSON.stringify(embeds)
+      if (next === reported) return
+      reported = next
+      post({ event: "embeds", params: { embeds } })
+    })
+  }
+
+  const show = (slide: number) => {
+    const all = slides()
+    current = Math.min(Math.max(1, Math.round(slide) || 1), Math.max(1, all.length))
+    all.forEach((element, index) => {
+      element.toggleAttribute("data-current", index + 1 === current)
+    })
+    if (root.dataset.mode === "overview") {
+      all[current - 1]?.scrollIntoView({ block: "nearest" })
+    }
+    reportEmbeds()
+  }
+
+  const handle = (method: string, params: Record<string, unknown>) => {
+    switch (method) {
+      case "theme": {
+        // In the theme's layer, not inline: the deck's own CSS, unlayered, still wins.
+        const tokens = (params.tokens ?? {}) as Record<string, string>
+        const declarations = Object.entries(tokens)
+          .filter(
+            ([name, value]) =>
+              /^--[a-z0-9-]+$/.test(name) && typeof value === "string" && !/[;{}<]/.test(value)
+          )
+          .map(([name, value]) => `${name}: ${value};`)
+        // The stage is the app's, in the app's colors, whatever a deck makes of its own tokens.
+        for (const [stage, token] of [
+          ["--sixb-stage", "--muted"],
+          ["--sixb-stage-border", "--border"],
+          ["--sixb-stage-foreground", "--foreground"],
+        ]) {
+          const value = declarations.find((declaration) => declaration.startsWith(`${token}:`))
+          if (value) declarations.push(`${stage}${value.slice(token.length)}`)
+        }
+        let style = document.getElementById("sixb-theme")
+        if (!style) {
+          style = document.createElement("style")
+          style.id = "sixb-theme"
+          document.head.append(style)
+        }
+        style.textContent = `@layer sixb-theme { :root { ${declarations.join(" ")} color-scheme: ${params.dark === true ? "dark" : "light"}; } }`
+        root.classList.toggle("dark", params.dark === true)
+        return
+      }
+      case "goto":
+        show(Number(params.slide))
+        return
+      case "mode":
+        if (root.dataset.mode === "fill") return
+        root.dataset.mode =
+          params.mode === "overview" || params.mode === "present" ? params.mode : "slide"
+        fit()
+        show(current)
+        return
+      default:
+        throw new Error(`Unknown method '${method}'.`)
+    }
+  }
+
+  window.addEventListener("message", (event) => {
+    if (event.source !== window.parent) return
+    const data = event.data as Record<string, unknown> | null
+    // Requests only: at the top level, as in the layout check, the frame's own answers come back
+    // to it, and answering an answer would trade error messages with itself for good.
+    if (!data || data.protocol !== PROTOCOL || typeof data.id !== "number") return
+    if (typeof data.method !== "string") return
+    try {
+      handle(String(data.method), (data.params ?? {}) as Record<string, unknown>)
+      post({ id: data.id })
+    } catch (error) {
+      post({ id: data.id, error: error instanceof Error ? error.message : String(error) })
+    }
+  })
+
+  window.addEventListener("keydown", (event) => {
+    if (event.metaKey || event.ctrlKey || event.altKey) return
+    const target = event.target as HTMLElement | null
+    if (target?.closest("input, textarea, select, [contenteditable]")) return
+    if (!KEYS.includes(event.key)) return
+    event.preventDefault()
+    post({ event: "key", params: { key: event.key } })
+  })
+
+  document.addEventListener("click", (event) => {
+    const target = event.target as HTMLElement | null
+    const link = target?.closest<HTMLAnchorElement>("a[href]")
+    if (link) {
+      const href = link.getAttribute("href") ?? ""
+      if (/^artifact:/i.test(href.trim())) {
+        event.preventDefault()
+        post({ event: "open", params: { address: href.trim() } })
+      } else if (!href.startsWith("#")) {
+        // Outside the frame: a link opens in its own tab.
+        link.target = "_blank"
+        link.rel = "noopener noreferrer"
+      }
+      return
+    }
+    if (root.dataset.mode !== "overview") return
+    const slide = target?.closest<HTMLElement>("section.slide")
+    if (!slide) return
+    post({ event: "select", params: { slide: slides().indexOf(slide) + 1 } })
+  })
+
+  window.addEventListener("resize", () => {
+    fit()
+    reportEmbeds()
+  })
+  const ready = () => {
+    slides().forEach((element, index) => {
+      element.dataset.number = String(index + 1)
+    })
+    fit()
+    show(current)
+    post({ event: "ready", params: { slides: slides().length } })
+    // Fonts and images that arrive later move what is laid out after them.
+    const resized = new ResizeObserver(reportEmbeds)
+    for (const element of Array.from(document.querySelectorAll("section.slide > *, sixb-embed"))) {
+      resized.observe(element)
+    }
+    window.addEventListener("load", reportEmbeds)
+    document.fonts?.ready.then(reportEmbeds)
+  }
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", ready)
+  else ready()
+}

package/src/artifacts/html.ts

@@ -0,0 +1,25 @@
+const NAMED_ENTITIES: Readonly<Record<string, string>> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: String.fromCharCode(0xa0),
+}
+
+/**
+ * Text or an attribute as the browser reads it. HTMLRewriter hands both over as written in the
+ * HTML, entities included, so `artifact:…#Q3%20&amp;%20Q4` must read `&` before it is resolved.
+ */
+export function decodeHtmlEntities(value: string): string {
+  return value.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (match, entity: string) => {
+    if (entity[0] !== "#") return NAMED_ENTITIES[entity.toLowerCase()] ?? match
+    const codePoint =
+      entity[1]?.toLowerCase() === "x"
+        ? Number.parseInt(entity.slice(2), 16)
+        : Number(entity.slice(1))
+    return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 0x10ffff
+      ? String.fromCodePoint(codePoint)
+      : match
+  })
+}

package/src/artifacts/ids.ts

@@ -0,0 +1,18 @@
+// Lowercase base32 without the letters easiest to misread. Ten characters is 50 bits: short enough
+// for the Agent to write in an address, and the store refuses the rare collision.
+const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz"
+
+/** A new artifact id, such as `art_k3m9q2x7tp`. */
+export function createArtifactId(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(10))
+  let id = "art_"
+  for (const byte of bytes) id += ALPHABET[byte % ALPHABET.length]
+  return id
+}
+
+const ARTIFACT_ID = new RegExp(`^art_[${ALPHABET}]{10}$`)
+
+/** Whether `value` has the shape of an artifact id; whether that artifact exists is another matter. */
+export function isArtifactId(value: string): boolean {
+  return ARTIFACT_ID.test(value)
+}

package/src/artifacts/index.ts

@@ -0,0 +1,61 @@
+/**
+ * What a client needs to show an artifact the way publishing read it: the kinds and what each
+ * holds, the slugs its headings get, its theme, a sheet's workbook and CSV, the limits a version
+ * keeps within, the `artifact:` addresses that point into it, and the messages a viewer and a
+ * deck's frame exchange, versioned as `sixb-frame/1`. Browser-safe: no storage, no Bun APIs.
+ */
+
+export {
+  type ArtifactAddress,
+  type CellRange,
+  formatArtifactAddress,
+  isArtifactAddress,
+  parseArtifactAddress,
+  parseSheetPart,
+  type SheetPart,
+} from "./address"
+export { CsvParseError, type CsvTable, parseCsv } from "./csv"
+export {
+  type DeckMode,
+  FRAME_PROTOCOL,
+  FRAME_THEME_TOKENS,
+  type FrameEmbed,
+  type FrameEvent,
+  type FrameRequest,
+  type FrameResponse,
+  type FrameStart,
+  frameStartHash,
+  parseFrameEvent,
+} from "./frames/protocol"
+export { ARTIFACT_KINDS, type ArtifactKind } from "./kinds"
+export { ARTIFACT_LIMITS } from "./limits"
+export {
+  type ArtifactOutline,
+  createHeadingSlugger,
+  type DocumentHeading,
+  type DocumentOutline,
+  type FileOutline,
+  type SheetOutline,
+  type SheetSummary,
+  type SlidesOutline,
+} from "./outline"
+export {
+  type ArtifactAddressTarget,
+  type ResolvedArtifactPart,
+  resolveArtifactAddress,
+} from "./resolve"
+export { ARTIFACT_THEME_FILE, type ArtifactTheme, parseArtifactTheme } from "./theme"
+export {
+  NUMERIC_COLUMN_TYPES,
+  parseSheetDate,
+  parseSheetNumber,
+  parseWorkbook,
+  type SheetChartType,
+  type SheetColumnFormat,
+  type SheetColumnType,
+  sheetFilePath,
+  WORKBOOK_FILE,
+  type Workbook,
+  type WorkbookChart,
+  type WorkbookSheet,
+} from "./workbook"

package/src/artifacts/kinds.ts

@@ -0,0 +1,8 @@
+/** The kinds of artifact Sixb renders. An artifact's kind is fixed when it is created. */
+export const ARTIFACT_KINDS = ["document", "sheet", "slides", "file"] as const
+
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number]
+
+export function isArtifactKind(value: unknown): value is ArtifactKind {
+  return typeof value === "string" && (ARTIFACT_KINDS as readonly string[]).includes(value)
+}

package/src/artifacts/limits.ts

@@ -0,0 +1,27 @@
+/** What one version may hold. Publishing refuses a version over any of these. */
+export const ARTIFACT_LIMITS = {
+  maxFiles: 200,
+  maxFileBytes: 25 * 1024 * 1024,
+  maxVersionBytes: 100 * 1024 * 1024,
+  maxPathLength: 512,
+  maxTitleLength: 200,
+  /** A document's Markdown is parsed whole when it is published. */
+  maxDocumentBytes: 2 * 1024 * 1024,
+  maxThemeBytes: 4 * 1024,
+  maxWorkbookBytes: 256 * 1024,
+  /** A sheet's limits keep the grid quick and its charts readable. */
+  maxSheets: 20,
+  maxSheetRows: 100_000,
+  /** The viewer reads a sheet whole, and reads at most this much. */
+  maxSheetFileBytes: 5 * 1024 * 1024,
+  maxSheetColumns: 200,
+  maxCharts: 10,
+  maxChartSeries: 5,
+  /** One slice per theme chart color, so no two slices share one. */
+  maxPieSlices: 5,
+  /** A deck's `index.html` is parsed whole when it is published. */
+  maxDeckBytes: 2 * 1024 * 1024,
+  maxSlides: 100,
+  /** `artifact:` addresses one version may use. */
+  maxReferences: 200,
+} as const

package/src/artifacts/outline.ts

@@ -0,0 +1,62 @@
+/**
+ * What a version contains, read from its files when it is published. Addresses resolve against
+ * it, and previews and hover cards show it without opening the files.
+ */
+export type ArtifactOutline = DocumentOutline | SheetOutline | SlidesOutline | FileOutline
+
+export interface DocumentOutline {
+  readonly kind: "document"
+  readonly headings: readonly DocumentHeading[]
+}
+
+export interface DocumentHeading {
+  readonly depth: number
+  readonly text: string
+  /** What `#part` names in an address to this section. */
+  readonly slug: string
+}
+
+export interface SheetOutline {
+  readonly kind: "sheet"
+  readonly sheets: readonly SheetSummary[]
+  /** The names of the charts declared in the workbook. */
+  readonly charts: readonly string[]
+}
+
+export interface SheetSummary {
+  readonly name: string
+  readonly rows: number
+  readonly columns: readonly string[]
+}
+
+export interface SlidesOutline {
+  readonly kind: "slides"
+  /** One entry per slide, in order; the title is the slide's first heading. */
+  readonly slides: readonly { readonly title?: string }[]
+}
+
+export interface FileOutline {
+  readonly kind: "file"
+  readonly mediaType: string
+}
+
+/**
+ * Turns a document's heading texts, in order, into their section slugs: lowercase, punctuation
+ * dropped, spaces as hyphens, and `-1`, `-2` after a repeat. Publishing and the renderer both name
+ * sections with it, so an address to a section finds the heading the reader sees.
+ */
+export function createHeadingSlugger(): (text: string) => string {
+  const used = new Set<string>()
+  return (text) => {
+    const base =
+      text
+        .trim()
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .replace(/\s+/g, "-") || "section"
+    let slug = base
+    for (let repeat = 1; used.has(slug); repeat += 1) slug = `${base}-${repeat}`
+    used.add(slug)
+    return slug
+  }
+}

package/src/artifacts/publish/files.ts

@@ -0,0 +1,87 @@
+import { statFileRef } from "../../blob-storage/file-content"
+import type { BlobStorage } from "../../blob-storage/types"
+import { isValidFileRef } from "../../blob-storage/validation"
+import type { ArtifactFile } from "../../storage/artifacts/types"
+import { ArtifactRequestError } from "../errors"
+import { ARTIFACT_LIMITS } from "../limits"
+
+export type ArtifactBlobStorage = Pick<BlobStorage, "stat" | "open">
+
+/**
+ * Checks a version's files before anything reads them: safe unique paths, the per-version limits,
+ * and stored bytes that match each reference.
+ */
+export async function checkArtifactFiles(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<void> {
+  if (files.length === 0) throw invalidArtifact("A version needs at least one file.")
+  if (files.length > ARTIFACT_LIMITS.maxFiles) {
+    throw invalidArtifact(
+      `A version holds at most ${ARTIFACT_LIMITS.maxFiles} files; this one has ${files.length}.`
+    )
+  }
+
+  const paths = new Set<string>()
+  let totalBytes = 0
+  for (const entry of files) {
+    if (!isArtifactPath(entry.path)) {
+      throw invalidArtifact(
+        `'${entry.path}' is not a usable file path: use a relative path with / separators, no . or .. segments, and at most ${ARTIFACT_LIMITS.maxPathLength} characters.`
+      )
+    }
+    if (paths.has(entry.path)) throw invalidArtifact(`'${entry.path}' appears twice.`)
+    paths.add(entry.path)
+    if (!isValidFileRef(entry.file)) {
+      throw invalidArtifact(`'${entry.path}' does not have a valid file reference.`)
+    }
+    if (entry.file.sizeBytes > ARTIFACT_LIMITS.maxFileBytes) {
+      throw invalidArtifact(
+        `'${entry.path}' is ${entry.file.sizeBytes} bytes; a file may be at most ${ARTIFACT_LIMITS.maxFileBytes}.`
+      )
+    }
+    totalBytes += entry.file.sizeBytes
+  }
+  if (totalBytes > ARTIFACT_LIMITS.maxVersionBytes) {
+    throw invalidArtifact(
+      `The files total ${totalBytes} bytes; a version may hold at most ${ARTIFACT_LIMITS.maxVersionBytes}.`
+    )
+  }
+
+  const stored = await Promise.all(files.map((entry) => statFileRef(blobStorage, entry.file)))
+  const missing = files.find((_, index) => !stored[index])
+  if (missing) throw invalidArtifact(`'${missing.path}' refers to a file that is not stored.`)
+}
+
+/** The file at `path`, read as UTF-8 text when it is no larger than `maxBytes`. */
+export async function readArtifactText(
+  blobStorage: ArtifactBlobStorage,
+  file: ArtifactFile,
+  maxBytes: number
+): Promise<string> {
+  if (file.file.sizeBytes > maxBytes) {
+    throw invalidArtifact(
+      `'${file.path}' is ${file.file.sizeBytes} bytes; it may be at most ${maxBytes}.`
+    )
+  }
+  const text = await new Response(await blobStorage.open(file.file.blobId)).text()
+  // A byte-order mark is not part of the text.
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+}
+
+/** Relative, `/`-separated, no empty, `.`, or `..` segment, no backslash or control character. */
+export function isArtifactPath(path: string): boolean {
+  return (
+    typeof path === "string" &&
+    path.length > 0 &&
+    path.length <= ARTIFACT_LIMITS.maxPathLength &&
+    !path.startsWith("/") &&
+    !path.includes("\\") &&
+    !/[\u0000-\u001f\u007f]/.test(path) &&
+    path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..")
+  )
+}
+
+export function invalidArtifact(message: string): ArtifactRequestError {
+  return new ArtifactRequestError("invalid_artifact", `[Sixb] ${message}`)
+}