@tin.so/core 0.1.0 → 0.3.0

package/dist/{index-CtUX1lFe.d.mts → index-eoLihZJ2.d.mts}

@@ -1,101 +1,5 @@
 import * as v from "valibot";
 import { InitInput } from "@resvg/resvg-wasm";
-type FontFace = {
-  weight: number;
-  italic: boolean;
-  /** Path relative to the fonts directory of this package */
-  file: string;
-  /** Family name inside the font file, which resvg uses to match the face */
-  family: string;
-};
-type FontMetrics = {
-  unitsPerEm: number;
-  ascender: number;
-  descender: number;
-  lineGap: number;
-};
-type CodeFont = {
-  id: string;
-  name: string;
-  kind: "code";
-  faces: Array<FontFace>;
-  metrics: FontMetrics & {
-    advance: number;
-  };
-};
-type UiFont = {
-  id: string;
-  name: string;
-  kind: "ui";
-  faces: Array<FontFace>;
-  metrics: FontMetrics & {
-    advances: Record<string, number>;
-  };
-};
-type Font = CodeFont | UiFont;
-/** Reads a font file by its path relative to the fonts directory */
-type FontLoader = (file: string) => Promise<Uint8Array>;
-declare const CODE_FONTS: CodeFont[];
-declare const CODE_FONT_IDS: string[];
-declare const DEFAULT_CODE_FONT = "jetbrains-mono";
-declare const UI_FONT: UiFont;
-declare function getCodeFont(id: string): CodeFont;
-/** Picks the face that matches the style best: the exact face, then the regular face of the same style */
-declare function getFace(font: Font, style?: {
-  bold?: boolean;
-  italic?: boolean;
-}): FontFace;
-/**
- * The CSS font family of a face. The first name is for browsers, which load the faces with @font-face
- * rules under that name. The second name is the family inside the file, for resvg. The names stay
- * unquoted, because resvg does not match a quoted name that follows another name.
- */
-declare function cssFontFamily(font: Font, face: FontFace): string;
-/** Width of a text in the UI font, for title layout. Characters outside of ASCII count as an "M". */
-declare function measureUiText(text: string, fontSize: number): number;
-/** An icon on a 24px grid, drawn either filled or as a 2px stroke */
-type Icon = {
-  id: string;
-  title: string;
-  /** SVG elements of the icon, without the root element */
-  body: string;
-  style: "fill" | "stroke";
-};
-/** The icon of the language, from its id in the language list */
-declare const AUTO_ICON = "auto";
-declare const FILE_ICON = "file";
-declare const NO_ICON = "none";
-/** Icon ids that a pane can name, besides "auto" and "none" */
-declare const ICON_IDS: string[];
-declare function getIcon(id: string): Icon | undefined;
-/** Resolves the icon setting of a pane. Returns undefined for "none". */
-declare function resolveIcon(setting: string, language: string): Icon | undefined;
-/** The URL of the JSON Schema of the latest spec version, on the hosted app */
-declare const SPEC_SCHEMA_URL: string;
-/**
- * The spec as a JSON Schema, for editors and agents. JSON Schema cannot express the custom checks of
- * the spec, such as line ranges, so their rules are only in the descriptions.
- */
-declare function specJsonSchema(): Record<string, unknown>;
-/**
- * The hosted web app. The CLI takes another app from its TIN_APP_URL environment variable,
- * for example the local editor during development.
- */
-declare const DEFAULT_APP_URL = "https://code-image.zirkelc.workers.dev/";
-/**
- * Compresses a spec into a URL-safe string. A spec without a version gets version 1, so that the
- * link keeps its meaning when a later version changes the format.
- */
-declare function encodeSpec(spec: unknown): Promise<string>;
-/** Reads a spec from a string of the encoder, with the fields of older links changed */
-declare function decodeSpec(encoded: string): Promise<unknown>;
-/**
- * A link that opens the spec in the web app. The spec is in the fragment, so it never goes to a
- * server and has no length limit of a request line.
- */
-declare function createLink(spec: unknown, appUrl?: string): Promise<string>;
-/** Reads the spec from the fragment of a link, or returns undefined when the fragment has none */
-declare function readLink(link: string): Promise<unknown>;
 type Mode = "light" | "dark";
 /** Token colors of a theme. Keys that are missing use the foreground color. */
 type Syntax = {
@@ -125,16 +29,24 @@ type Theme = {
     from: string;
     to: string;
   };
-  font?: string;
-  partner?: boolean;
-  hidden?: boolean;
-  lineNumbers?: boolean;
+  /** The colors of the window by mode, as in the editor of the theme. The background is opaque. */
+  window?: Partial<Record<Mode, EditorWindow>>;
+  /** The Shiki theme by mode that colors the code, in place of the token colors of the syntax */
+  textmate: Partial<Record<Mode, string>>;
   syntax: {
     light?: Syntax;
     dark?: Syntax;
   };
 };
-/** Colors of the window around the code, from the ray.so default frame */
+/** The colors of the window of an editor theme */
+type EditorWindow = {
+  background: string;
+  /** The text of the title bar and the tabs */
+  title?: string;
+  lineNumber?: string;
+  divider?: string;
+};
+/** Colors of the window around the code, from the default frame of ray.so */
 type FrameColors = {
   /** The gradient behind the windows */
   backdrop: {
@@ -153,7 +65,7 @@ type FrameColors = {
 };
 declare const THEMES: Array<Theme>;
 declare const THEME_IDS: string[];
-declare const DEFAULT_THEME = "candy";
+declare const DEFAULT_THEME = "github";
 declare function getTheme(id: string): Theme;
 /** A theme with only one mode always uses that mode */
 declare function resolveMode(theme: Theme, mode: Mode): Mode;
@@ -183,6 +95,101 @@ declare function resolveLanguage(language: string): string;
 declare function inferLanguage(fileName: string | undefined): string;
 /** Splits code into lines of colored tokens with the colors of the theme */
 declare function highlight(code: string, language: string, theme: Theme, mode: Mode, syntax: Syntax): Promise<Array<HighlightedLine>>;
+/**
+ * Backgrounds that the renderer makes from the colors of the image:
+ * - ambient-blur: a blurred and larger copy of the code behind the window
+ * - ambient-code: a mesh of the colors that the code uses most
+ * - ambient-theme: a mesh of the keyword, string, function and constant colors of the theme
+ */
+declare const AMBIENT_BACKGROUNDS: readonly ["ambient-blur", "ambient-code", "ambient-theme"];
+declare const AMBIENT_ENABLED = false;
+type AmbientBackground = (typeof AMBIENT_BACKGROUNDS)[number];
+declare function isAmbientBackground(css: string): css is AmbientBackground;
+/** The theme mesh of a theme in a mode, as a preview of the ambient backgrounds before the code is known */
+declare function ambientPreviewCss(theme: Theme, mode: Mode): string;
+/** A background preset of the editor: a gradient, a color or a mesh of radial gradients */
+type BackgroundPreset = {
+  id: string;
+  name: string;
+  kind: "gradient" | "color" | "mesh";
+  /** The CSS background, as the background field of a spec takes it */
+  css: string;
+};
+declare const BACKGROUNDS: Array<BackgroundPreset>;
+/** The background preset of a theme in a mode, or undefined when the theme has none */
+declare function themeBackground(theme: Theme, mode: Mode): BackgroundPreset | undefined;
+type FontFace = {
+  weight: number;
+  italic: boolean;
+  /** Path relative to the fonts directory of this package */
+  file: string;
+  /** Family name inside the font file, which resvg uses to match the face */
+  family: string;
+};
+type FontMetrics = {
+  unitsPerEm: number;
+  ascender: number;
+  descender: number;
+  lineGap: number;
+};
+type CodeFont = {
+  id: string;
+  name: string;
+  kind: "code";
+  faces: Array<FontFace>;
+  metrics: FontMetrics & {
+    advance: number;
+  };
+};
+type UiFont = {
+  id: string;
+  name: string;
+  kind: "ui";
+  faces: Array<FontFace>;
+  metrics: FontMetrics & {
+    advances: Record<string, number>;
+  };
+};
+type Font = CodeFont | UiFont;
+/** Reads a font file by its path relative to the fonts directory */
+type FontLoader = (file: string) => Promise<Uint8Array>;
+declare const CODE_FONTS: CodeFont[];
+declare const CODE_FONT_IDS: string[];
+declare const DEFAULT_CODE_FONT = "jetbrains-mono";
+declare const UI_FONT: UiFont;
+declare function getCodeFont(id: string): CodeFont;
+/** Picks the face that matches the style best: the exact face, then the regular face of the same style */
+declare function getFace(font: Font, style?: {
+  bold?: boolean;
+  italic?: boolean;
+}): FontFace;
+/**
+ * The CSS font family of a face. The first name is for browsers, which load the faces with @font-face
+ * rules under that name. The second name is the family inside the file, for resvg. The names stay
+ * unquoted, because resvg does not match a quoted name that follows another name.
+ */
+declare function cssFontFamily(font: Font, face: FontFace): string;
+/** Width of a text in the UI font, for title layout. Characters outside of ASCII count as an "M". */
+/** The width of text in a code font, which gives each character the same advance */
+declare function measureCodeText(text: string, fontSize: number, font: CodeFont): number;
+declare function measureUiText(text: string, fontSize: number): number;
+/** An icon on a 24px grid, drawn either filled or as a 2px stroke */
+type Icon = {
+  id: string;
+  title: string;
+  /** SVG elements of the icon, without the root element */
+  body: string;
+  style: "fill" | "stroke";
+};
+/** The icon of the language, from its id in the language list */
+declare const AUTO_ICON = "auto";
+declare const FILE_ICON = "file";
+declare const NO_ICON = "none";
+/** Icon ids that a pane can name, besides "auto" and "none" */
+declare const ICON_IDS: string[];
+declare function getIcon(id: string): Icon | undefined;
+/** Resolves the icon setting of a pane. Returns undefined for "none". */
+declare function resolveIcon(setting: string, language: string): Icon | undefined;
 declare const MAC_HEADER: {
   paddingTop: number;
   height: number;
@@ -234,6 +241,8 @@ type AnnotationBox = {
   lines: Array<HighlightedLine>;
   /** true when the popover is smaller than its code, so that it must cut the code off */
   clipped: boolean;
+  /** The background of the popover from the spec */
+  background?: string;
 };
 type PaneBox = Rect & {
   title?: string;
@@ -279,6 +288,8 @@ type WindowBox = Rect & {
   radius: number;
   title?: string;
   controls: "gray" | "color";
+  /** The background of the window from the spec, in place of the theme color */
+  background?: string;
   /** The size that fits the panes. The layout can make a window larger to fill the image. */
   natural: {
     width: number;
@@ -302,7 +313,14 @@ type Scene = {
   mode: Mode;
   syntax: Syntax;
   frame: FrameColors;
+  /** false for a transparent image */
   background: boolean;
+  /** The opacity of the background, from 0 to 1 */
+  backgroundOpacity: number;
+  /** The color or gradient of the image: the one of the spec, or the background preset of the theme */
+  customBackground: CssBackground | undefined;
+  /** Draw a blurred copy of the code of each window behind it, over the background color */
+  ambientBlur: boolean;
   font: CodeFont;
   text: TextMetrics;
   popoverText: TextMetrics;
@@ -321,6 +339,99 @@ type LayoutOptions = {
 declare function normalizeCode(code: string, options?: LayoutOptions): string;
 /** Validates the spec, highlights the code and places every element of the image */
 declare function layout(input: unknown, options?: LayoutOptions): Promise<Scene>;
+/**
+ * The CSS backgrounds that a spec can use: a color, or layers of linear-gradient and
+ * radial-gradient with an optional color as the last layer. Colors are hex, rgb(), rgba() and
+ * transparent.
+ */
+type Rgba = {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+};
+type Length = {
+  value: number;
+  unit: "%" | "px";
+};
+type ColorStop = {
+  color: Rgba;
+  position?: Length;
+};
+type Extent = "closest-side" | "closest-corner" | "farthest-side" | "farthest-corner";
+type LinearLayer = {
+  type: "linear";
+  /** An angle in degrees, or the corner or side of a "to" keyword as -1, 0 or 1 on each axis */
+  direction: {
+    angle: number;
+  } | {
+    to: {
+      x: number;
+      y: number;
+    };
+  };
+  stops: Array<ColorStop>;
+};
+type RadialLayer = {
+  type: "radial";
+  shape: "circle" | "ellipse";
+  size: Extent | {
+    x: Length;
+    y: Length;
+  };
+  at: {
+    x: Length;
+    y: Length;
+  };
+  stops: Array<ColorStop>;
+};
+type ColorLayer = {
+  type: "color";
+  color: Rgba;
+};
+type Layer = LinearLayer | RadialLayer | ColorLayer;
+/** A parsed CSS background, with the top layer first as in CSS */
+type CssBackground = Array<Layer>;
+declare function isCssBackground(css: string): boolean;
+/** The URL of the JSON Schema of the latest spec version, on the hosted app */
+declare const SPEC_SCHEMA_URL: string;
+/**
+ * The spec as a JSON Schema, for editors and agents. JSON Schema cannot express the custom checks of
+ * the spec, such as line ranges, so their rules are only in the descriptions.
+ */
+declare function specJsonSchema(): Record<string, unknown>;
+/**
+ * True when the value is the URL of a tin.so spec schema: a path that ends with
+ * /schema/v<number>.json on the host of the hosted app, on an earlier host of the app, or on the
+ * host of the given app URL (for example a local editor).
+ */
+declare function isSpecSchemaUrl(value: unknown, appUrl?: string): boolean;
+/**
+ * The hosted web app. The CLI takes another app from its TIN_APP_URL environment variable,
+ * for example the local editor during development.
+ */
+declare const DEFAULT_APP_URL = "https://tin.so/";
+type DecodeOptions = {
+  /** The largest size of the inflated spec in bytes, so that a hostile input cannot use much memory */
+  maxBytes?: number;
+};
+/**
+ * Compresses a spec into a URL-safe string. A spec without a version gets version 1, so that the
+ * link keeps its meaning when a later version changes the format.
+ */
+declare function encodeSpec(spec: unknown): Promise<string>;
+/**
+ * Reads a spec from a string of the encoder, with the fields of older links changed. Throws for
+ * bad data and for a spec larger than the limit.
+ */
+declare function decodeSpec(encoded: string, options?: DecodeOptions): Promise<unknown>;
+/**
+ * A link that opens the spec in the web app. The spec is in the fragment, so it never goes to a
+ * server and has no length limit of a request line.
+ */
+declare function createLink(spec: unknown, appUrl?: string): Promise<string>;
+/** Reads the spec from the fragment of a link, or returns undefined when the fragment has none */
+declare function readLink(link: string, options?: DecodeOptions): Promise<unknown>;
 /**
  * Whether a render writes the metadata when the caller does not say. This is the one place to
  * change the default.
@@ -332,14 +443,16 @@ declare const SOFTWARE = "tin.so";
 declare const PNG_KEYWORDS: {
   readonly software: "Software";
   readonly source: "Source";
-  readonly link: "code-image:link";
-  readonly spec: "code-image:spec";
+  readonly link: "tin.so:link";
 };
 /** The namespace of the metadata element in an SVG */
-declare const SVG_NAMESPACE = "urn:code-image:metadata:1";
-/** The data that an exported image carries, so that the editor can open the image again */
+declare const SVG_NAMESPACE = "urn:tin.so:metadata:1";
+/**
+ * The data that an exported image carries, so that the editor can open the image again. The image
+ * stores only the link, because the link holds the whole spec.
+ */
 type ImageMetadata = {
-  /** The spec input, as the user wrote it */
+  /** The spec input, as the user wrote it, with its version */
   spec: unknown;
   /** A link that opens the spec in the editor */
   link: string;
@@ -350,8 +463,8 @@ type ImageMetadata = {
  */
 declare function createImageMetadata(spec: unknown, appUrl?: string): Promise<ImageMetadata>;
 /**
- * Adds text chunks after the header of a PNG: the program, the app URL, the editor link and the
- * compressed spec. A PNG without the expected header comes back unchanged.
+ * Adds text chunks after the header of a PNG: the program, the app URL and the editor link. A PNG
+ * without the expected header comes back unchanged.
  */
 declare function addPngMetadata(png: Uint8Array, metadata: ImageMetadata): Promise<Uint8Array>;
 /**
@@ -362,14 +475,19 @@ declare function addPngMetadata(png: Uint8Array, metadata: ImageMetadata): Promi
 declare function readImageSpec(input: Uint8Array | ArrayBuffer | Blob | string): Promise<unknown>;
 declare const IMPLICIT_SPEC_VERSION = 1;
 /**
- * Changes the fields of older specs from before the v field to the current fields, so that old
- * links, files and images stay valid. Input that is not a spec stays as it is, so that the spec
- * validation reports it.
+ * The version that the $schema URL of a spec names, or undefined when the spec has no such URL.
+ * Only the path counts, so that the URL of each host that serves the schema gives the version.
  */
-declare function migrateLegacySpec(spec: unknown): unknown;
+declare function schemaVersion(spec: unknown): number | undefined;
+/**
+ * Keys with this prefix hold data of other tools, such as an editor state. The renderer ignores
+ * them in each object of a spec, so that a spec with such keys stays valid in all versions.
+ */
+declare const EXTENSION_PREFIX = "x-";
 /**
  * Adds the version to a spec without one, so that a stored spec keeps its meaning when a later
- * version changes the format. A spec with a version stays as it is.
+ * version changes the format. The version comes from the $schema URL, or is version 1 without it.
+ * A spec with a version stays as it is.
  */
 declare function stampSpecVersion(spec: unknown): unknown;
 type PngOptions = {
@@ -400,12 +518,19 @@ declare const SPEC_LIMITS: {
   readonly size: 8192;
 };
 declare const MARK_STYLES: readonly ["strong", "emphasis", "underline", "strikethrough"];
+declare const ANNOTATION_TYPES: readonly ["popover"];
 /**
  * Versions of the spec format.
  *
  * - Increase v only for a breaking change: a field that changes its meaning, gets a new name or
- *   goes away. A new optional field does not increase v, because older specs stay valid.
- * - A spec without v is version 1, now and in all later versions, because older specs have no v.
+ *   goes away, a changed default, a value that a list no longer has (a theme, font, icon or
+ *   language id), or a smaller limit. Specs leave out the defaults, so a new default changes old
+ *   images. A new optional field, a new value or a larger limit does not increase v, because older
+ *   specs stay valid.
+ * - The version is v, or the version of the $schema URL (/schema/v<number>.json) without v. When
+ *   both are there, they must be the same. A spec without both is version 1, now and in all later
+ *   versions, because older specs have neither.
+ * - Keys that start with "x-" are for other tools. The renderer ignores them in every object.
  * - For a new version, add its schema (with v as a required literal of the new number) to
  *   SPEC_SCHEMAS, a function that changes a parsed spec of the version before into the new
  *   version to MIGRATIONS, and increase LATEST_SPEC_VERSION. The schema of the latest version is
@@ -416,9 +541,10 @@ declare const LATEST_SPEC_VERSION = 1;
 declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
   readonly $schema: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>, undefined>, v.DescriptionAction<string | undefined, string>]>;
   readonly v: v.SchemaWithPipe<readonly [v.OptionalSchema<v.LiteralSchema<1, undefined>, 1>, v.DescriptionAction<1, string>]>;
-  readonly theme: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<string[], undefined>, "candy">, v.DescriptionAction<string, string>]>;
+  readonly theme: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<string[], undefined>, "github">, v.DescriptionAction<string, string>]>;
   readonly mode: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<["dark", "light"], undefined>, "dark">, v.DescriptionAction<"dark" | "light", string>]>;
-  readonly background: v.SchemaWithPipe<readonly [v.OptionalSchema<v.BooleanSchema<undefined>, true>, v.DescriptionAction<boolean, string>]>;
+  readonly background: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Use a hex color such as \"#1e1e2e\", or a CSS gradient such as \"linear-gradient(135deg, #2e1065, #a78bfa)\". Gradients are linear-gradient and radial-gradient, with hex, rgb(), rgba() or transparent colors, several layers separated by commas, and a color as the last layer">]>, undefined>, v.DescriptionAction<string | undefined, string>]>;
+  readonly backgroundOpacity: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 1, undefined>]>, 1>, v.DescriptionAction<number, string>]>;
   readonly padding: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>, v.MaxValueAction<number, 256, undefined>]>, 64>, v.DescriptionAction<number, string>]>;
   readonly font: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<string[], undefined>, undefined>, v.DescriptionAction<string | undefined, string>]>;
   readonly lineNumbers: v.SchemaWithPipe<readonly [v.OptionalSchema<v.BooleanSchema<undefined>, undefined>, v.DescriptionAction<boolean | undefined, string>]>;
@@ -431,6 +557,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
     readonly frame: v.SchemaWithPipe<readonly [v.OptionalSchema<v.BooleanSchema<undefined>, true>, v.DescriptionAction<boolean, string>]>;
     readonly titleBar: v.SchemaWithPipe<readonly [v.OptionalSchema<v.BooleanSchema<undefined>, true>, v.DescriptionAction<boolean, string>]>;
     readonly tabs: v.SchemaWithPipe<readonly [v.OptionalSchema<v.BooleanSchema<undefined>, false>, v.DescriptionAction<boolean, string>]>;
+    readonly background: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Use a hex color such as \"#ff5c57\"">]>, undefined>, v.DescriptionAction<string | undefined, string>]>;
     readonly controls: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<["gray", "color"], undefined>, "gray">, v.DescriptionAction<"color" | "gray", string>]>;
     readonly title: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, v.DescriptionAction<string | undefined, string>]>;
     readonly split: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<["row", "column"], undefined>, "row">, v.DescriptionAction<"column" | "row", string>]>;
@@ -446,6 +573,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       readonly icon: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<["auto", "none", ...string[]], undefined>, "auto">, v.DescriptionAction<string, string>]>;
       readonly lineNumbers: v.SchemaWithPipe<readonly [v.OptionalSchema<v.BooleanSchema<undefined>, undefined>, v.DescriptionAction<boolean | undefined, string>]>;
       readonly annotations: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly type: v.SchemaWithPipe<readonly [v.OptionalSchema<v.PicklistSchema<readonly ["popover"], undefined>, "popover">, v.DescriptionAction<"popover", string>]>;
         readonly line: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, v.DescriptionAction<number, string>]>;
         readonly match: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, v.DescriptionAction<string, string>]>;
         readonly occurrence: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>, v.DescriptionAction<number, string>]>;
@@ -491,7 +619,9 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[], string>]>;
+        readonly background: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Use a hex color such as \"#ff5c57\"">]>, undefined>, v.DescriptionAction<string | undefined, string>]>;
       }, undefined>, undefined>, v.MaxLengthAction<{
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -509,7 +639,9 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[], number, (issue: v.MaxLengthIssue<{
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -527,7 +659,9 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[], number>) => string>]>, readonly []>, v.DescriptionAction<{
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -545,6 +679,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[], string>]>;
       readonly marks: v.SchemaWithPipe<readonly [v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
         readonly line: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, v.DescriptionAction<number, string>]>;
@@ -591,6 +726,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -608,6 +744,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -626,6 +763,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -643,6 +781,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -661,6 +800,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -678,6 +818,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -696,6 +837,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -713,6 +855,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -728,6 +871,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
     frame: boolean;
     titleBar: boolean;
     tabs: boolean;
+    background?: string | undefined;
     controls: "color" | "gray";
     title?: string | undefined;
     split: "column" | "row";
@@ -743,6 +887,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -760,6 +905,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -775,6 +921,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
     frame: boolean;
     titleBar: boolean;
     tabs: boolean;
+    background?: string | undefined;
     controls: "color" | "gray";
     title?: string | undefined;
     split: "column" | "row";
@@ -790,6 +937,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -807,6 +955,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -822,6 +971,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
     frame: boolean;
     titleBar: boolean;
     tabs: boolean;
+    background?: string | undefined;
     controls: "color" | "gray";
     title?: string | undefined;
     split: "column" | "row";
@@ -837,6 +987,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -854,6 +1005,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -869,6 +1021,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
     frame: boolean;
     titleBar: boolean;
     tabs: boolean;
+    background?: string | undefined;
     controls: "color" | "gray";
     title?: string | undefined;
     split: "column" | "row";
@@ -884,6 +1037,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -901,6 +1055,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -918,7 +1073,8 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
   v: 1;
   theme: string;
   mode: "dark" | "light";
-  background: boolean;
+  background?: string | undefined;
+  backgroundOpacity: number;
   padding: number;
   font?: string | undefined;
   lineNumbers?: boolean | undefined;
@@ -931,6 +1087,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
     frame: boolean;
     titleBar: boolean;
     tabs: boolean;
+    background?: string | undefined;
     controls: "color" | "gray";
     title?: string | undefined;
     split: "column" | "row";
@@ -946,6 +1103,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -963,6 +1121,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -980,7 +1139,8 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
   v: 1;
   theme: string;
   mode: "dark" | "light";
-  background: boolean;
+  background?: string | undefined;
+  backgroundOpacity: number;
   padding: number;
   font?: string | undefined;
   lineNumbers?: boolean | undefined;
@@ -993,6 +1153,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
     frame: boolean;
     titleBar: boolean;
     tabs: boolean;
+    background?: string | undefined;
     controls: "color" | "gray";
     title?: string | undefined;
     split: "column" | "row";
@@ -1008,6 +1169,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
       icon: string;
       lineNumbers?: boolean | undefined;
       annotations: {
+        type: "popover";
         line: number;
         match: string;
         occurrence: number;
@@ -1025,6 +1187,7 @@ declare const SpecSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{
           color?: string | undefined;
           background?: string | undefined;
         }[];
+        background?: string | undefined;
       }[];
       marks: {
         line: number;
@@ -1055,9 +1218,9 @@ declare class SpecError extends Error {
   constructor(issues: Array<string>);
 }
 /**
- * Validates a spec and applies the defaults. It first changes the fields of older specs, then
- * validates the spec with the schema of its version and changes it to the latest version. Throws
- * a SpecError that lists every issue.
+ * Validates a spec and applies the defaults. It first removes the keys of other tools, then
+ * validates the spec with the schema of its version and changes it to the latest version. Throws a
+ * SpecError that lists every issue.
  */
 declare function parseSpec(input: unknown): Spec;
 /** Expands highlight entries such as [2, "4-6"] to a set of line numbers, up to the last line */
@@ -1073,4 +1236,4 @@ type SvgOptions = {
 };
 /** Writes the scene as a standalone SVG document */
 declare function toSvg(scene: Scene, options?: SvgOptions): string;
-export { resolveLanguage as $, readImageSpec as A, FontFace as At, WINDOW_RADIUS as B, ImageMetadata as C, getIcon as Ct, SVG_NAMESPACE as D, CodeFont as Dt, SOFTWARE as E, CODE_FONT_IDS as Et, PaneBox as F, cssFontFamily as Ft, MAC_HEADER as G, cellCount as H, Rect as I, getCodeFont as It, PLAIN_TEXT as J, HighlightedLine as K, Scene as L, getFace as Lt, LINE_HEIGHT as M, FontMetrics as Mt, LayoutOptions as N, UI_FONT as Nt, addPngMetadata as O, DEFAULT_CODE_FONT as Ot, POPOVER as P, UiFont as Pt, isKnownLanguage as Q, TAB_HEADER as R, measureUiText as Rt, stampSpecVersion as S, NO_ICON as St, PNG_KEYWORDS as T, CODE_FONTS as Tt, layout as U, WindowBox as V, normalizeCode as W, highlight as X, Token as Y, inferLanguage as Z, loadSceneFonts as _, specJsonSchema as _t, MarkStyle as a, THEME_IDS as at, IMPLICIT_SPEC_VERSION as b, ICON_IDS as bt, Spec as c, getSyntax as ct, SpecSchema as d, DEFAULT_APP_URL as dt, DEFAULT_THEME as et, WindowSpec as f, createLink as ft, initPng as g, SPEC_SCHEMA_URL as gt, PngOptions as h, readLink as ht, MARK_STYLES as i, THEMES as it, FONT_SIZE as j, FontLoader as jt, createImageMetadata as k, Font as kt, SpecError as l, getTheme as lt, parseSpec as m, encodeSpec as mt, toSvg as n, Mode as nt, PaneSpec as o, Theme as ot, expandLineRanges as p, decodeSpec as pt, LANGUAGE_IDS as q, LATEST_SPEC_VERSION as r, Syntax as rt, SPEC_LIMITS as s, getFrameColors as st, SvgOptions as t, FrameColors as tt, SpecInput as u, resolveMode as ut, sceneFontFiles as v, AUTO_ICON as vt, METADATA_BY_DEFAULT as w, resolveIcon as wt, migrateLegacySpec as x, Icon as xt, svgToPng as y, FILE_ICON as yt, TextMetrics as z };
+export { WindowBox as $, resolveMode as $t, addPngMetadata as A, AMBIENT_ENABLED as At, isSpecSchemaUrl as B, isKnownLanguage as Bt, schemaVersion as C, getFace as Ct, PNG_KEYWORDS as D, BackgroundPreset as Dt, METADATA_BY_DEFAULT as E, BACKGROUNDS as Et, createLink as F, LANGUAGE_IDS as Ft, LayoutOptions as G, Mode as Gt, isCssBackground as H, DEFAULT_THEME as Ht, decodeSpec as I, PLAIN_TEXT as It, Rect as J, THEME_IDS as Jt, POPOVER as K, Syntax as Kt, encodeSpec as L, Token as Lt, readImageSpec as M, ambientPreviewCss as Mt, DEFAULT_APP_URL as N, isAmbientBackground as Nt, SOFTWARE as O, themeBackground as Ot, DecodeOptions as P, HighlightedLine as Pt, WINDOW_RADIUS as Q, getTheme as Qt, readLink as R, highlight as Rt, IMPLICIT_SPEC_VERSION as S, getCodeFont as St, ImageMetadata as T, measureUiText as Tt, FONT_SIZE as U, EditorWindow as Ut, specJsonSchema as V, resolveLanguage as Vt, LINE_HEIGHT as W, FrameColors as Wt, TAB_HEADER as X, getFrameColors as Xt, Scene as Y, Theme as Yt, TextMetrics as Z, getSyntax as Zt, initPng as _, FontLoader as _t, MARK_STYLES as a, FILE_ICON as at, svgToPng as b, UiFont as bt, SPEC_LIMITS as c, NO_ICON as ct, SpecInput as d, CODE_FONTS as dt, cellCount as et, SpecSchema as f, CODE_FONT_IDS as ft, PngOptions as g, FontFace as gt, parseSpec as h, Font as ht, LATEST_SPEC_VERSION as i, AUTO_ICON as it, createImageMetadata as j, AmbientBackground as jt, SVG_NAMESPACE as k, AMBIENT_BACKGROUNDS as kt, Spec as l, getIcon as lt, expandLineRanges as m, DEFAULT_CODE_FONT as mt, toSvg as n, normalizeCode as nt, MarkStyle as o, ICON_IDS as ot, WindowSpec as p, CodeFont as pt, PaneBox as q, THEMES as qt, ANNOTATION_TYPES as r, MAC_HEADER as rt, PaneSpec as s, Icon as st, SvgOptions as t, layout as tt, SpecError as u, resolveIcon as ut, loadSceneFonts as v, FontMetrics as vt, stampSpecVersion as w, measureCodeText as wt, EXTENSION_PREFIX as x, cssFontFamily as xt, sceneFontFiles as y, UI_FONT as yt, SPEC_SCHEMA_URL as z, inferLanguage as zt };