@sixb/core 0.1.20 → 0.1.21

package/src/artifacts/publish/validate/sheet.ts

@@ -0,0 +1,251 @@
+import { posix } from "node:path"
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import { isArtifactAddress } from "../../address"
+import { CsvParseError, type CsvTable, parseCsv } from "../../csv"
+import { ARTIFACT_LIMITS } from "../../limits"
+import type { SheetOutline } from "../../outline"
+import {
+  NUMERIC_COLUMN_TYPES,
+  parseSheetDate,
+  parseSheetNumber,
+  parseWorkbook,
+  type SheetColumnFormat,
+  sheetFilePath,
+  WORKBOOK_FILE,
+  type Workbook,
+  type WorkbookSheet,
+} from "../../workbook"
+import { type ArtifactBlobStorage, invalidArtifact, readArtifactText } from "../files"
+import type { FoundReference } from "../references"
+
+/**
+ * Reads a sheet: `workbook.json`, then each sheet's CSV against it. Every cell of a typed column
+ * must read as its type and every chart must name columns its sheet has, so the grid formats and
+ * the charts draw the same wherever the sheet is opened.
+ */
+export async function validateSheet(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<{
+  readonly entry: string
+  readonly outline: SheetOutline
+  readonly references: readonly FoundReference[]
+}> {
+  const byPath = new Map(files.map((file) => [file.path, file]))
+  const workbookFile = byPath.get(WORKBOOK_FILE)
+  if (!workbookFile) {
+    throw invalidArtifact(
+      `A sheet is a directory: '${WORKBOOK_FILE}' listing its sheets, and one CSV per sheet under sheets/. A single CSV publishes as a file.`
+    )
+  }
+  const parsed = parseWorkbook(
+    await readArtifactText(blobStorage, workbookFile, ARTIFACT_LIMITS.maxWorkbookBytes)
+  )
+  if ("error" in parsed) throw invalidArtifact(parsed.error)
+  const { workbook } = parsed
+
+  const declared = new Set(workbook.sheets.map((sheet) => sheetFilePath(sheet.name)))
+  const stray = files.find((file) => file.path.startsWith("sheets/") && !declared.has(file.path))
+  if (stray) {
+    throw invalidArtifact(
+      `'${stray.path}' is not a sheet in ${WORKBOOK_FILE}: list it in "sheets", or move it out of sheets/.`
+    )
+  }
+
+  const tables = new Map<string, CsvTable>()
+  const references: FoundReference[] = []
+  for (const sheet of workbook.sheets) {
+    tables.set(sheet.name, await readSheet(blobStorage, byPath, sheet, references))
+  }
+  checkCharts(workbook, tables)
+
+  return {
+    entry: WORKBOOK_FILE,
+    outline: {
+      kind: "sheet",
+      sheets: workbook.sheets.map((sheet) => {
+        const table = tables.get(sheet.name)
+        return {
+          name: sheet.name,
+          rows: table?.rows.length ?? 0,
+          columns: [...(table?.header ?? [])],
+        }
+      }),
+      charts: workbook.charts.map((chart) => chart.name),
+    },
+    references,
+  }
+}
+
+async function readSheet(
+  blobStorage: ArtifactBlobStorage,
+  byPath: ReadonlyMap<string, ArtifactFile>,
+  sheet: WorkbookSheet,
+  references: FoundReference[]
+): Promise<CsvTable> {
+  const path = sheetFilePath(sheet.name)
+  const file = byPath.get(path)
+  if (!file) throw invalidArtifact(`Sheet '${sheet.name}' needs its values in '${path}'.`)
+
+  if (file.file.sizeBytes > ARTIFACT_LIMITS.maxSheetFileBytes) {
+    throw invalidArtifact(
+      `'${path}' is ${megabytes(file.file.sizeBytes)} MB; a sheet's values may be at most ${megabytes(ARTIFACT_LIMITS.maxSheetFileBytes)} MB, which is what the viewer reads. Split it into several sheets, or publish the CSV as a file.`
+    )
+  }
+  let table: CsvTable
+  try {
+    table = parseCsv(await readArtifactText(blobStorage, file, ARTIFACT_LIMITS.maxSheetFileBytes))
+  } catch (error) {
+    if (error instanceof CsvParseError) throw invalidArtifact(`'${path}': ${error.message}`)
+    throw error
+  }
+
+  const { header, rows } = table
+  if (header.length === 0)
+    throw invalidArtifact(`'${path}' is empty: its first line names the columns.`)
+  if (header.length > ARTIFACT_LIMITS.maxSheetColumns) {
+    throw invalidArtifact(
+      `'${path}' has ${header.length} columns; a sheet holds at most ${ARTIFACT_LIMITS.maxSheetColumns}.`
+    )
+  }
+  const seen = new Set<string>()
+  for (const [index, name] of header.entries()) {
+    if (!name.trim()) {
+      throw invalidArtifact(`'${path}' column ${index + 1} has no name in the header row.`)
+    }
+    if (seen.has(name)) throw invalidArtifact(`'${path}' has two columns named '${name}'.`)
+    seen.add(name)
+  }
+  if (rows.length > ARTIFACT_LIMITS.maxSheetRows) {
+    throw invalidArtifact(
+      `'${path}' has ${rows.length} rows; a sheet holds at most ${ARTIFACT_LIMITS.maxSheetRows}.`
+    )
+  }
+  for (const [index, row] of rows.entries()) {
+    if (row.length > header.length) {
+      throw invalidArtifact(
+        `'${path}' row ${index + 2} has ${row.length} fields; the header names ${header.length} columns.`
+      )
+    }
+  }
+
+  for (const column of [...Object.keys(sheet.columns), ...Object.keys(sheet.widths)]) {
+    if (!seen.has(column)) {
+      throw invalidArtifact(
+        `${WORKBOOK_FILE} sheet '${sheet.name}' names column '${column}', which '${path}' does not have.`
+      )
+    }
+  }
+  for (const [column, format] of Object.entries(sheet.columns)) {
+    const index = header.indexOf(column)
+    if (format.type === "link" || format.type === "image") {
+      // A link or image may be another artifact's address, resolved with the rest.
+      for (const [rowIndex, row] of table.rows.entries()) {
+        const value = row[index]?.trim() ?? ""
+        if (!isArtifactAddress(value)) continue
+        references.push({
+          address: value,
+          as: format.type === "image" ? "embed" : "link",
+          at: `${sheet.name}!${columnLetter(index)}${rowIndex + 2}`,
+        })
+      }
+    }
+    checkColumn(path, table, index, column, format, byPath)
+  }
+  return table
+}
+
+function checkColumn(
+  path: string,
+  table: CsvTable,
+  index: number,
+  column: string,
+  format: SheetColumnFormat,
+  byPath: ReadonlyMap<string, ArtifactFile>
+): void {
+  for (const [rowIndex, row] of table.rows.entries()) {
+    const value = row[index] ?? ""
+    if (!value.trim() || isArtifactAddress(value)) continue
+    const problem = cellProblem(value, format, byPath)
+    if (problem) {
+      throw invalidArtifact(
+        `'${path}' row ${rowIndex + 2}, column '${column}': ${JSON.stringify(value)} ${problem}`
+      )
+    }
+  }
+}
+
+function cellProblem(
+  value: string,
+  format: SheetColumnFormat,
+  byPath: ReadonlyMap<string, ArtifactFile>
+): string | undefined {
+  switch (format.type) {
+    case "number":
+    case "currency":
+      return parseSheetNumber(value) === undefined
+        ? "is not a number: write plain digits, such as 4120000 or -3.5, with no symbols or separators."
+        : undefined
+    case "percent":
+      return parseSheetNumber(value) === undefined
+        ? "is not a number: write a percent as a fraction, such as 0.351 for 35.1%."
+        : undefined
+    case "date":
+      return parseSheetDate(value) === undefined
+        ? "is not a date: write YYYY-MM-DD, or an ISO 8601 date and time."
+        : undefined
+    case "link":
+      return /^https?:\/\/[^\s]+$/i.test(value.trim())
+        ? undefined
+        : "is not a link: write a full https:// address, or another artifact's address."
+    case "image": {
+      const imagePath = posix.normalize(value.trim())
+      return byPath.has(imagePath)
+        ? undefined
+        : "is not one of the artifact's files: add the image to the artifact and give its relative path, or give another artifact's address."
+    }
+    case "text":
+      return undefined
+  }
+}
+
+function checkCharts(workbook: Workbook, tables: ReadonlyMap<string, CsvTable>): void {
+  for (const chart of workbook.charts) {
+    const sheet = workbook.sheets.find((candidate) => candidate.name === chart.sheet)
+    const table = tables.get(chart.sheet)
+    if (!sheet || !table) continue
+    for (const column of [chart.x, ...chart.y]) {
+      if (!table.header.includes(column)) {
+        throw invalidArtifact(
+          `${WORKBOOK_FILE} chart '${chart.name}' plots column '${column}', which sheet '${chart.sheet}' does not have.`
+        )
+      }
+    }
+    for (const column of chart.y) {
+      const type = sheet.columns[column]?.type ?? "text"
+      if (!NUMERIC_COLUMN_TYPES.includes(type)) {
+        throw invalidArtifact(
+          `${WORKBOOK_FILE} chart '${chart.name}' plots column '${column}', which is ${type}; give it a number, currency, or percent type in "columns".`
+        )
+      }
+    }
+    if (chart.type === "pie" && table.rows.length > ARTIFACT_LIMITS.maxPieSlices) {
+      throw invalidArtifact(
+        `${WORKBOOK_FILE} chart '${chart.name}' is a pie with ${table.rows.length} slices; a pie reads well with at most ${ARTIFACT_LIMITS.maxPieSlices}. Use a bar chart instead.`
+      )
+    }
+  }
+}
+
+/** A column's letter as a spreadsheet shows it: A, Z, AA. */
+function columnLetter(index: number): string {
+  let letters = ""
+  for (let rest = index + 1; rest > 0; rest = Math.floor((rest - 1) / 26)) {
+    letters = String.fromCharCode(65 + ((rest - 1) % 26)) + letters
+  }
+  return letters
+}
+
+function megabytes(bytes: number): string {
+  return (bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, "")
+}

package/src/artifacts/publish/validate/slides.ts

@@ -0,0 +1,134 @@
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import { isArtifactAddress, parseArtifactAddress } from "../../address"
+import { decodeHtmlEntities } from "../../html"
+import { ARTIFACT_LIMITS } from "../../limits"
+import type { SlidesOutline } from "../../outline"
+import { type ArtifactBlobStorage, invalidArtifact, readArtifactText } from "../files"
+import type { FoundReference } from "../references"
+
+/** The file a deck renders from. */
+export const SLIDES_ENTRY = "index.html"
+
+/** Where the frame serves the kit and the runtime, beside a deck's own files. */
+export const FRAME_ASSET_PREFIX = "__sixb/"
+
+/**
+ * Reads a deck: `index.html` with one `<section class="slide">` per 1280×720 slide, and the files
+ * it loads beside it. Each slide's first heading becomes its title in the outline. The `artifact:`
+ * addresses it uses are returned with the slide each is on, to resolve: links (`<a href>`), files
+ * it shows from other artifacts (`<img src>`), and anything else it shows (`<sixb-embed src>`), a
+ * chart, a range, a section, or a slide, which the app draws over the frame.
+ */
+export async function validateSlides(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<{
+  readonly entry: string
+  readonly outline: SlidesOutline
+  readonly references: readonly FoundReference[]
+}> {
+  const entry = files.find((file) => file.path === SLIDES_ENTRY)
+  if (!entry) {
+    throw invalidArtifact(
+      `A deck needs '${SLIDES_ENTRY}' with one <section class="slide"> per slide.`
+    )
+  }
+  const reserved = files.find((file) => file.path.startsWith(FRAME_ASSET_PREFIX))
+  if (reserved) {
+    throw invalidArtifact(
+      `'${reserved.path}' is under ${FRAME_ASSET_PREFIX}, where Sixb serves the deck's kit and runtime: move it.`
+    )
+  }
+  const html = await readArtifactText(blobStorage, entry, ARTIFACT_LIMITS.maxDeckBytes)
+
+  const slides: { title: string; heading: boolean }[] = []
+  const references: FoundReference[] = []
+  let refused: string | undefined
+  const at = () => String(Math.max(1, slides.length))
+  // The heading being read, if it is the first of the current slide.
+  let reading: { title: string; heading: boolean } | null = null
+  new HTMLRewriter()
+    .on("section", {
+      element(element) {
+        const classes = (element.getAttribute("class") ?? "").split(/\s+/)
+        if (classes.includes("slide")) slides.push({ title: "", heading: false })
+      },
+    })
+    .on("h1, h2, h3", {
+      element(element) {
+        const slide = slides.at(-1)
+        if (!slide || slide.heading) return
+        slide.heading = true
+        reading = slide
+        element.onEndTag(() => {
+          reading = null
+        })
+      },
+      text(chunk) {
+        if (reading) reading.title += chunk.text
+      },
+    })
+    .on("a[href]", {
+      element(element) {
+        const href = decodeHtmlEntities(element.getAttribute("href") ?? "")
+        if (isArtifactAddress(href)) {
+          references.push({ address: href.trim(), as: "link", at: at() })
+        }
+      },
+    })
+    .on("img[src]", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "").trim()
+        if (!isArtifactAddress(source)) return
+        if (!parseArtifactAddress(source)?.path) {
+          refused ??= `An <img> shows a file from another artifact, and '${source}' names none: show a chart, a range, a section, or a slide with <sixb-embed src="${source}"></sixb-embed>.`
+          return
+        }
+        references.push({ address: source, as: "embed", at: at() })
+      },
+    })
+    .on("sixb-embed", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "").trim()
+        if (!isArtifactAddress(source)) {
+          refused ??= `<sixb-embed> shows another artifact: give it src="artifact:…", such as artifact:art_k3m9q2x7tp#chart=revenue.`
+          return
+        }
+        references.push({ address: source, as: "embed", at: at() })
+      },
+    })
+    .on("iframe[src], object[data], embed[src]", {
+      element(element) {
+        const source = decodeHtmlEntities(
+          element.getAttribute("src") ?? element.getAttribute("data") ?? ""
+        ).trim()
+        if (isArtifactAddress(source)) {
+          refused ??= `${SLIDES_ENTRY} frames '${source}': show another artifact with <sixb-embed src="${source}"></sixb-embed>, or a file of one with <img>.`
+        }
+      },
+    })
+    .transform(html)
+
+  if (refused) throw invalidArtifact(refused)
+  if (slides.length === 0) {
+    throw invalidArtifact(
+      `${SLIDES_ENTRY} has no slides: put each slide in a <section class="slide">.`
+    )
+  }
+  if (slides.length > ARTIFACT_LIMITS.maxSlides) {
+    throw invalidArtifact(
+      `A deck holds at most ${ARTIFACT_LIMITS.maxSlides} slides; this one has ${slides.length}.`
+    )
+  }
+  return {
+    entry: SLIDES_ENTRY,
+    outline: {
+      kind: "slides",
+      slides: slides.map(({ title }) => {
+        const plain = decodeHtmlEntities(title).replace(/\s+/g, " ").trim()
+        return plain ? { title: plain } : {}
+      }),
+    },
+    references,
+  }
+}

package/src/artifacts/references.ts

@@ -0,0 +1,11 @@
+/** An `artifact:` address a version uses, recorded when the version is published. */
+export interface ArtifactReference {
+  /** The address as written, such as `artifact:art_k3m9q2x7tp#chart=revenue`. */
+  readonly address: string
+  /** An embed shows the target in place; a link opens it. */
+  readonly as: "embed" | "link"
+  /** Where the address sits in its host: a heading slug, a slide number, or a sheet cell. */
+  readonly at: string
+  /** The target's version when this version was published, so later changes can be told apart. */
+  readonly resolvedVersion: number
+}

package/src/artifacts/resolve.ts

@@ -0,0 +1,97 @@
+import { type ArtifactAddress, type CellRange, parseSheetPart } from "./address"
+import type { ArtifactKind } from "./kinds"
+import type { ArtifactOutline } from "./outline"
+
+/** The version an address points into: its kind, its outline, and its file list. */
+export interface ArtifactAddressTarget {
+  readonly kind: ArtifactKind
+  readonly outline: ArtifactOutline
+  readonly files: readonly { readonly path: string }[]
+}
+
+/** What an address names inside its target. */
+export type ResolvedArtifactPart =
+  | { readonly type: "artifact" }
+  | { readonly type: "file"; readonly path: string }
+  | { readonly type: "sheet"; readonly sheet: string; readonly range?: CellRange }
+  | { readonly type: "chart"; readonly chart: string }
+  | { readonly type: "section"; readonly slug: string }
+  | { readonly type: "slide"; readonly slide: number }
+
+/**
+ * Finds what an address names in a version, against its outline and files. A problem says what is
+ * missing and what the version has instead, so whoever wrote the address can fix it.
+ */
+export function resolveArtifactAddress(
+  address: ArtifactAddress,
+  target: ArtifactAddressTarget
+): { readonly part: ResolvedArtifactPart } | { readonly problem: string } {
+  if (address.path !== undefined) {
+    if (address.part !== undefined) return { problem: "names both a file and a part of one" }
+    return target.files.some((file) => file.path === address.path)
+      ? { part: { type: "file", path: address.path } }
+      : { problem: `has no file '${address.path}'` }
+  }
+  if (address.part === undefined) return { part: { type: "artifact" } }
+
+  const { outline } = target
+  switch (outline.kind) {
+    case "sheet": {
+      const part = parseSheetPart(address.part)
+      if (!part) {
+        return {
+          problem: `has no part '${address.part}': name a sheet, a range such as Summary!A1:D12, or chart=<name>`,
+        }
+      }
+      if (part.type === "chart") {
+        return outline.charts.includes(part.chart)
+          ? { part }
+          : { problem: `has no chart '${part.chart}'${listed("its charts", outline.charts)}` }
+      }
+      const sheet = outline.sheets.find((candidate) => candidate.name === part.sheet)
+      if (!sheet) {
+        return {
+          problem: `has no sheet '${part.sheet}'${listed(
+            "its sheets",
+            outline.sheets.map((candidate) => candidate.name)
+          )}`,
+        }
+      }
+      // Row 1 is the header row, so the last row is one past the data rows.
+      if (
+        part.range &&
+        (part.range.bottom > sheet.rows || part.range.right >= sheet.columns.length)
+      ) {
+        return {
+          problem: `has no range ${address.part.slice(address.part.lastIndexOf("!") + 1)} in sheet '${sheet.name}', which has ${sheet.rows + 1} rows and ${sheet.columns.length} columns`,
+        }
+      }
+      return { part }
+    }
+    case "document": {
+      const heading = outline.headings.find((candidate) => candidate.slug === address.part)
+      return heading
+        ? { part: { type: "section", slug: heading.slug } }
+        : {
+            problem: `has no section '${address.part}'${listed(
+              "its sections",
+              outline.headings.map((candidate) => candidate.slug)
+            )}`,
+          }
+    }
+    case "slides": {
+      const slide = /^[1-9]\d*$/.test(address.part) ? Number(address.part) : Number.NaN
+      return slide <= outline.slides.length
+        ? { part: { type: "slide", slide } }
+        : { problem: `has no slide '${address.part}': it has ${outline.slides.length} slides` }
+    }
+    case "file":
+      return { problem: `is a ${target.kind}, which has no parts to name` }
+  }
+}
+
+function listed(label: string, names: readonly string[]): string {
+  if (names.length === 0) return ""
+  const shown = names.slice(0, 8).map((name) => `'${name}'`)
+  return `; ${label} are ${shown.join(", ")}${names.length > shown.length ? ", …" : ""}`
+}

package/src/artifacts/theme.ts

@@ -0,0 +1,116 @@
+/** An artifact may carry this file at its root to override the app's theme. */
+export const ARTIFACT_THEME_FILE = "theme.json"
+
+/**
+ * An artifact's own theme. `mode` pins light or dark whatever the viewer's app uses; `tokens`
+ * override the app's values for the names in {@link ARTIFACT_THEME_TOKENS}.
+ */
+export interface ArtifactTheme {
+  readonly mode?: "light" | "dark"
+  readonly tokens?: Readonly<Record<string, string>>
+}
+
+const COLOR_TOKENS = [
+  "--background",
+  "--foreground",
+  "--card",
+  "--card-foreground",
+  "--muted",
+  "--muted-foreground",
+  "--primary",
+  "--primary-foreground",
+  "--accent",
+  "--accent-foreground",
+  "--border",
+  "--chart-1",
+  "--chart-2",
+  "--chart-3",
+  "--chart-4",
+  "--chart-5",
+] as const
+const FONT_TOKENS = ["--font-sans", "--font-serif", "--font-mono"] as const
+
+/** The tokens a theme may set. Every other app token stays the app's. */
+export const ARTIFACT_THEME_TOKENS: readonly string[] = [
+  ...COLOR_TOKENS,
+  ...FONT_TOKENS,
+  "--radius",
+]
+
+// Values land in CSS custom properties, so each kind of token takes one narrow shape: nothing that
+// could close the declaration, open a URL, or call a function other than a color space.
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i
+const FUNCTION_COLOR =
+  /^(?:rgba?|hsla?|oklch|oklab|lab|lch)\((?:[\d.%\s,/+-]|deg|turn|rad|none)*\)$/i
+const FONT_FAMILY =
+  /^\s*(?:"[\w -]+"|'[\w -]+'|[\w-]+)(?:\s*,\s*(?:"[\w -]+"|'[\w -]+'|[\w-]+))*\s*$/
+const LENGTH = /^(?:0|\d{1,3}(?:\.\d+)?(?:px|rem|em))$/
+
+/** Reads a `theme.json`. Returns the reason it was refused, in words the author can act on. */
+export function parseArtifactTheme(
+  text: string
+): { readonly theme: ArtifactTheme } | { readonly error: string } {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch {
+    return { error: `${ARTIFACT_THEME_FILE} is not valid JSON.` }
+  }
+  if (!isObject(value)) return { error: `${ARTIFACT_THEME_FILE} must be a JSON object.` }
+
+  const unknownKey = Object.keys(value).find((key) => key !== "mode" && key !== "tokens")
+  if (unknownKey) {
+    return {
+      error: `${ARTIFACT_THEME_FILE} has '${unknownKey}'; it takes only "mode" and "tokens".`,
+    }
+  }
+  if (value.mode !== undefined && value.mode !== "light" && value.mode !== "dark") {
+    return { error: `${ARTIFACT_THEME_FILE} "mode" must be "light" or "dark".` }
+  }
+  if (value.tokens !== undefined && !isObject(value.tokens)) {
+    return { error: `${ARTIFACT_THEME_FILE} "tokens" must be an object of token names to values.` }
+  }
+
+  const tokens: Record<string, string> = {}
+  for (const [name, tokenValue] of Object.entries(value.tokens ?? {})) {
+    if (!ARTIFACT_THEME_TOKENS.includes(name)) {
+      return {
+        error: `${ARTIFACT_THEME_FILE} sets '${name}'. A theme can set ${ARTIFACT_THEME_TOKENS.join(", ")}.`,
+      }
+    }
+    if (typeof tokenValue !== "string" || !tokenValueFits(name, tokenValue)) {
+      return {
+        error: `${ARTIFACT_THEME_FILE} gives '${name}' a value it cannot use: ${expected(name)}.`,
+      }
+    }
+    tokens[name] = tokenValue.trim()
+  }
+
+  return {
+    theme: {
+      ...(value.mode === undefined ? {} : { mode: value.mode }),
+      ...(Object.keys(tokens).length === 0 ? {} : { tokens }),
+    },
+  }
+}
+
+function tokenValueFits(name: string, value: string): boolean {
+  const trimmed = value.trim()
+  if (name === "--radius") return LENGTH.test(trimmed)
+  if ((FONT_TOKENS as readonly string[]).includes(name)) {
+    return trimmed.length <= 200 && FONT_FAMILY.test(trimmed)
+  }
+  return HEX_COLOR.test(trimmed) || FUNCTION_COLOR.test(trimmed)
+}
+
+function expected(name: string): string {
+  if (name === "--radius") return "a length such as 8px or 0.5rem"
+  if ((FONT_TOKENS as readonly string[]).includes(name)) {
+    return 'a font list such as "Inter Tight", system-ui, sans-serif'
+  }
+  return "a color such as #2f7280 or oklch(0.62 0.1 210)"
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/artifacts/warnings.ts

@@ -0,0 +1,10 @@
+/**
+ * Something about a published version worth fixing that did not stop it from publishing. A warning
+ * names the part it concerns, so a viewer can point at it.
+ */
+export interface ArtifactWarning {
+  readonly code: string
+  readonly message: string
+  /** The slide, sheet, section, or file the warning is about. */
+  readonly part?: string
+}