@coldsmirk/inkstone-core 0.28.1 → 0.29.0

package/README.md

@@ -10,7 +10,7 @@ Part of [inkstone](https://github.com/coldsmirk/inkstone). The editor layers ([`
 - **`configureHighlighter(config)`** — extend or replace the default grammar / theme set, and choose the regex engine, once, before any editor mounts. `DEFAULT_HIGHLIGHTER_LANGS` is exported so extension is additive. `engine` takes the engine itself, a promise of one, or a factory called once when the highlighter is first built — configuration stays synchronous while the engine may be async to make: the strict JavaScript engine by default, `createJavaScriptRegexEngine({ forgiving: true })` for grammars the strict one refuses, or `onigurumaEngine`.
 - **`onigurumaEngine`** — the Oniguruma engine on its WASM, inlined into a chunk of your own bundle (about 600 KB, nothing fetched from anywhere else) and instantiated once, in about 20 ms. Which engine: the JavaScript one translates each grammar's patterns into JavaScript at the first tokenization, on the main thread, and pays for it on whole files — a TypeScript file's first sixty lines cost it about 170 ms, against Oniguruma's 20. Colouring fenced snippets, keep the default; reading whole files in an editor (`@coldsmirk/inkstone-monaco`'s Shiki bridge, `<MonacoEditor>`), pass `onigurumaEngine` as the factory. `onigurumaEngine(wasm)` takes the WASM from elsewhere in any form Shiki's `createOnigurumaEngine` accepts, such as a `fetch("/onig.wasm")`.
 - **`shikiThemeId(dark)`** plus the `INKSTONE_LIGHT_THEME` / `INKSTONE_DARK_THEME` constants — the theme names to pass wherever a Shiki theme id is expected.
-- **`configureEditorSurface(surfaces)`** — re-light every color the editors paint that is not syntax, in your design language, once, before any editor mounts. Per scheme, CSS color literals for the editor (`background` — content, gutter and the fields of its chrome — `lineHighlight`, `lineNumber`, `lineNumberActive`, `cursor`, `selection`, `scrollbar`), its floating chrome — completion, hover, parameter hints, the find widget and search panels, the context menu — (`widget`, `widgetBorder`, `widgetSelection`, `widgetForeground`, `widgetForegroundMuted`), the `accent` that rings a focused field and marks what a completion matched, and the diagnostic severities `error`, `warning`, `info` and `hint`, named as CodeMirror's `Diagnostic.severity` names them. The catppuccin pair keeps its syntax palette — token colors, the editor's default text, the completion-kind icons that mirror them — and gets these baked into its theme colors — Monaco, static rendering, and CodeMirror's chrome all read the same values — so an editor sits inside the app instead of bringing a second dark. A role or scheme left out keeps the flavor's own color, a later call replaces the schemes it names, and values must be hex colors (`#rrggbb`, `#rrggbbaa`) — Monaco parses theme colors as hex and paints red for anything else, so a `var()` reference or an `rgb(…)` is refused up front. Keep `lineHighlight` translucent: CodeMirror draws selections behind the content, so an opaque active line would hide them. `selection` shows at half its alpha while the editor is unfocused, in both engines; `scrollbar` has no hover state (CodeMirror's `scrollbar-color` has none, so Monaco's slider keeps it too). `getEditorSurface(dark)` reads what was configured.
+- **`configureEditorColors(config)`** — set every color the editors paint that is not syntax (a VS Code theme's `colors`, beside its `tokenColors`) in your design language, once, before any editor mounts. Per scheme, CSS color literals for the editor (`background` — content, gutter and the fields of its chrome — `lineHighlight`, `lineNumber`, `lineNumberActive`, `cursor`, `selection`, `scrollbar`), its floating chrome — completion, hover, parameter hints, the find widget and search panels, the context menu — (`widget`, `widgetBorder`, `widgetSelection`, `widgetForeground`, `widgetForegroundMuted`), the `accent` that rings a focused field and marks what a completion matched, and the diagnostic severities `error`, `warning`, `info` and `hint`, named as CodeMirror's `Diagnostic.severity` names them. The catppuccin pair keeps its syntax palette — token colors, the editor's default text, the completion-kind icons that mirror them — and gets these baked into its theme colors — Monaco, static rendering, and CodeMirror's chrome all read the same values — so an editor sits inside the app instead of bringing a second dark. A role or scheme left out keeps the flavor's own color, a later call replaces the schemes it names, and values must be hex colors (`#rrggbb`, `#rrggbbaa`) — Monaco parses theme colors as hex and paints red for anything else, so a `var()` reference or an `rgb(…)` is refused up front. Keep `lineHighlight` translucent: CodeMirror draws selections behind the content, so an opaque active line would hide them. `selection` shows at half its alpha while the editor is unfocused, in both engines; `scrollbar` has no hover state (CodeMirror's `scrollbar-color` has none, so Monaco's slider keeps it too). `getEditorColors(dark)` reads what was configured, and `withEditorColors(theme, colors)` applies a set of them to a Shiki theme of your own.
 - **`CODE_FONT_FAMILY`** — the shared code font stack both editor engines render with: the page's `--inkstone-font-family-code` CSS token when defined, else the platform's native monospace.
 - **`inkstoneRadius(size, fallback)` / `inkstoneShadow(size, fallback)`** — `var()` references to the host's `--inkstone-radius-{small,medium,large,xlarge}` and `--inkstone-shadow-{medium,large,xlarge}` tokens. Set them once on your root and both engines' chrome follows: the Monaco host maps them onto VS Code's `--vscode-cornerRadius-*` / `--vscode-shadow-*` design tokens (which the standalone editor never defines), CodeMirror's polish reads them directly; unset, each engine keeps the look it ships with.
 
@@ -25,7 +25,7 @@ pnpm add @coldsmirk/inkstone-core
 ## Quick start
 
 ```ts
-import { configureEditorSurface, configureHighlighter, DEFAULT_HIGHLIGHTER_LANGS, getHighlighter, onigurumaEngine, shikiThemeId } from "@coldsmirk/inkstone-core";
+import { configureEditorColors, configureHighlighter, DEFAULT_HIGHLIGHTER_LANGS, getHighlighter, onigurumaEngine, shikiThemeId } from "@coldsmirk/inkstone-core";
 import yaml from "@shikijs/langs/yaml";
 
 // Optional: add grammars/themes beyond the defaults — once, before any editor mounts — and,
@@ -33,7 +33,7 @@ import yaml from "@shikijs/langs/yaml";
 configureHighlighter({ langs: [...DEFAULT_HIGHLIGHTER_LANGS, yaml], engine: onigurumaEngine });
 
 // Optional: paint the editors' chrome in your own tokens (syntax colors stay catppuccin's).
-configureEditorSurface({
+configureEditorColors({
   light: { background: "#f7f7fa", lineHighlight: "#16171a0a", widget: "#ffffff", widgetBorder: "#ced4da", accent: "#228be6", error: "#e03131" },
   dark: { background: "#1d1b22", lineHighlight: "#ffffff0a", widget: "#302e38", widgetBorder: "#423f4b", accent: "#4dabf7", error: "#ff6b6b" }
 });

package/dist/index.d.ts

@@ -8,19 +8,20 @@ import { Awaitable, HighlighterCore, HighlighterCore as HighlighterCore$1, Langu
  */
 declare const CODE_FONT_FAMILY = "var(--inkstone-font-family-code, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace)";
 //#endregion
-//#region src/surface.d.ts
-/**
- * The colors an editor paints that are not its syntax, as a host's design language names
- * them. A host that configures these keeps the catppuccin flavors' syntax palette and gets the
- * editor's own chrome — background, gutter, current line, caret and selection, the floating
- * completion / hover / find widgets and the signals on them — in its own tokens, so an editor
- * sits inside the app instead of bringing a second dark.
+//#region src/editor-colors.d.ts
+/**
+ * The colors an editor paints that are not its syntax — a VS Code theme's `colors` beside its
+ * `tokenColors` — as a host's design language names them. A host that configures these keeps
+ * the catppuccin flavors' syntax palette and gets the editor's own chrome — background, gutter,
+ * current line, caret and selection, the floating completion / hover / find widgets and the
+ * signals on them — in its own tokens, so an editor sits inside the app instead of bringing a
+ * second dark.
  *
  * Every value is a hex color (`#rrggbb`, `#rrggbbaa`): Monaco parses its theme colors itself,
  * as hex only, and cannot follow a custom property. An omitted role keeps the flavor's own
  * color.
  */
-interface EditorSurface {
+interface EditorColors {
   /**
    * The editor's own background: the content area and the gutter, and the fields inside
    * floating chrome.
@@ -102,12 +103,20 @@ interface EditorSurface {
   hint?: string;
 }
 /**
- * One surface per color scheme; an omitted scheme keeps the flavor's own surfaces.
+ * The editor colors of each color scheme; an omitted scheme keeps the flavor's own.
  */
-interface EditorSurfaces {
-  light?: EditorSurface;
-  dark?: EditorSurface;
+interface EditorColorsConfig {
+  light?: EditorColors;
+  dark?: EditorColors;
 }
+/**
+ * A flavor with its editor colors repainted from `colors`: the token colors (the syntax
+ * palette) are untouched, only the theme colors behind each configured role change. Returns
+ * the theme itself when there is nothing to apply.
+ */
+declare function withEditorColors(theme: ThemeRegistration, colors: EditorColors | undefined): ThemeRegistration;
+//#endregion
+//#region src/host-tokens.d.ts
 /**
  * The corner-radius sizes both editors read from the host: `--inkstone-radius-<size>`. Monaco
  * maps them onto VS Code's own `--vscode-cornerRadius-*` design tokens (which the standalone
@@ -130,12 +139,6 @@ type ShadowSize = "medium" | "large" | "xlarge";
  * A `var()` reference to the host's `--inkstone-shadow-<size>` token with the given fallback.
  */
 declare function inkstoneShadow(size: ShadowSize, fallback: string): string;
-/**
- * A flavor with its surfaces repainted from `surface`: the token colors (the syntax palette)
- * are untouched, only the theme colors behind each configured role change. Returns the theme
- * itself when there is nothing to apply.
- */
-declare function surfacedTheme(theme: ThemeRegistration, surface: EditorSurface | undefined): ThemeRegistration;
 //#endregion
 //#region src/shiki.d.ts
 /**
@@ -202,23 +205,23 @@ declare function onigurumaEngine(wasm?: LoadWasmOptions): Promise<RegexEngine>;
  */
 declare function configureHighlighter(options: HighlighterConfig): void;
 /**
- * Re-light the editors' surfaces in the host's own colors, once, before the first
- * {@link getHighlighter} call — the catppuccin pair is registered with these surfaces baked in
- * (Monaco reads them from the theme, static rendering too), and CodeMirror's chrome reads them
- * at mount. A scheme left out keeps the flavor's own surfaces; a role left out keeps that
- * role's flavor color; a later call replaces the schemes it names. Process-global like the
- * highlighter itself, for the same reason: one palette across every editor and rendered block.
+ * Paint the editors in the host's own colors, once, before the first {@link getHighlighter}
+ * call — the catppuccin pair is registered with these colors baked in (Monaco reads them from
+ * the theme, static rendering too), and CodeMirror's chrome reads them at mount. A scheme left
+ * out keeps the flavor's own colors; a role left out keeps that role's flavor color; a later
+ * call replaces the schemes it names. Process-global like the highlighter itself, for the same
+ * reason: one palette across every editor and rendered block.
  *
  * Every value must be a hex color (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) — Monaco parses
  * theme colors as hex and paints red for anything else, a custom property reference or an
  * `rgb(…)` alike, so those are refused here instead of failing on screen.
  */
-declare function configureEditorSurface(surfaces: EditorSurfaces): void;
+declare function configureEditorColors(config: EditorColorsConfig): void;
 /**
- * The surface configured for a color scheme through {@link configureEditorSurface}, or
- * undefined when the flavor's own surfaces stand.
+ * The editor colors configured for a color scheme through {@link configureEditorColors}, or
+ * undefined when the flavor's own colors stand.
  */
-declare function getEditorSurface(dark: boolean): EditorSurface | undefined;
+declare function getEditorColors(dark: boolean): EditorColors | undefined;
 /**
  * The shared Shiki highlighter, built lazily on first call.
  *
@@ -239,4 +242,4 @@ declare function getHighlighter(): Promise<HighlighterCore$1>;
  */
 declare function shikiThemeId(dark: boolean): string;
 //#endregion
-export { CODE_FONT_FAMILY, DEFAULT_HIGHLIGHTER_LANGS, type EditorSurface, type EditorSurfaces, type HighlighterConfig, type HighlighterCore, INKSTONE_DARK_THEME, INKSTONE_LIGHT_THEME, type RadiusSize, type ShadowSize, configureEditorSurface, configureHighlighter, getEditorSurface, getHighlighter, inkstoneRadius, inkstoneShadow, onigurumaEngine, shikiThemeId, surfacedTheme };
+export { CODE_FONT_FAMILY, DEFAULT_HIGHLIGHTER_LANGS, type EditorColors, type EditorColorsConfig, type HighlighterConfig, type HighlighterCore, INKSTONE_DARK_THEME, INKSTONE_LIGHT_THEME, type RadiusSize, type ShadowSize, configureEditorColors, configureHighlighter, getEditorColors, getHighlighter, inkstoneRadius, inkstoneShadow, onigurumaEngine, shikiThemeId, withEditorColors };

package/dist/index.js

@@ -10,14 +10,8 @@ import { createOnigurumaEngine } from "shiki/engine/oniguruma";
 //#region src/code-font.ts
 const CODE_FONT_FAMILY = "var(--inkstone-font-family-code, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace)";
 //#endregion
-//#region src/surface.ts
-function inkstoneRadius(size, fallback) {
-	return `var(--inkstone-radius-${size}, ${fallback})`;
-}
-function inkstoneShadow(size, fallback) {
-	return `var(--inkstone-shadow-${size}, ${fallback})`;
-}
-const SURFACE_COLORS = {
+//#region src/editor-colors.ts
+const EDITOR_COLOR_KEYS = {
 	background: [
 		"editor.background",
 		"editorGutter.background",
@@ -120,22 +114,30 @@ const SURFACE_COLORS = {
 	],
 	hint: ["editorHint.foreground"]
 };
-function surfacedTheme(theme, surface) {
-	const roles = Object.entries(SURFACE_COLORS);
-	const colors = { ...theme.colors };
+function withEditorColors(theme, colors) {
+	const roles = Object.entries(EDITOR_COLOR_KEYS);
+	const themeColors = { ...theme.colors };
 	let changed = false;
 	for (const [role, keys] of roles) {
-		const value = surface?.[role];
+		const value = colors?.[role];
 		if (value === void 0) continue;
-		for (const key of keys) colors[key] = value;
+		for (const key of keys) themeColors[key] = value;
 		changed = true;
 	}
 	return changed ? {
 		...theme,
-		colors
+		colors: themeColors
 	} : theme;
 }
 //#endregion
+//#region src/host-tokens.ts
+function inkstoneRadius(size, fallback) {
+	return `var(--inkstone-radius-${size}, ${fallback})`;
+}
+function inkstoneShadow(size, fallback) {
+	return `var(--inkstone-shadow-${size}, ${fallback})`;
+}
+//#endregion
 //#region src/shiki.ts
 const INKSTONE_LIGHT_THEME = "catppuccin-latte";
 const INKSTONE_DARK_THEME = "catppuccin-macchiato";
@@ -180,19 +182,19 @@ function configureHighlighter(options) {
 	};
 }
 const HEX_COLOR = /^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i;
-function configureEditorSurface(surfaces) {
+function configureEditorColors(config) {
 	const registry = getHighlighterRegistry();
-	assertConfigurable(registry, "configureEditorSurface");
-	for (const [scheme, surface] of Object.entries(surfaces)) {
-		const roles = Object.entries(surface ?? {});
-		for (const [role, value] of roles) if (typeof value === "string" && !HEX_COLOR.test(value)) throw new Error(`configureEditorSurface: ${scheme}.${role} must be a hex color, which is all Monaco parses (${value})`);
+	assertConfigurable(registry, "configureEditorColors");
+	for (const [scheme, colors] of Object.entries(config)) {
+		const roles = Object.entries(colors ?? {});
+		for (const [role, value] of roles) if (typeof value === "string" && !HEX_COLOR.test(value)) throw new Error(`configureEditorColors: ${scheme}.${role} must be a hex color, which is all Monaco parses (${value})`);
 	}
 	registry.surfaces = {
 		...registry.surfaces,
-		...surfaces
+		...config
 	};
 }
-function getEditorSurface(dark) {
+function getEditorColors(dark) {
 	const { surfaces } = getHighlighterRegistry();
 	return dark ? surfaces.dark : surfaces.light;
 }
@@ -202,8 +204,8 @@ function getHighlighter() {
 	if (existing) return existing;
 	const attempt = createHighlighterCore({
 		themes: [
-			surfacedTheme(catppuccinLatte, registry.surfaces.light),
-			surfacedTheme(catppuccinMacchiato, registry.surfaces.dark),
+			withEditorColors(catppuccinLatte, registry.surfaces.light),
+			withEditorColors(catppuccinMacchiato, registry.surfaces.dark),
 			...registry.config.themes ?? []
 		],
 		langs: registry.config.langs ?? [...DEFAULT_HIGHLIGHTER_LANGS],
@@ -219,4 +221,4 @@ function shikiThemeId(dark) {
 	return dark ? INKSTONE_DARK_THEME : INKSTONE_LIGHT_THEME;
 }
 //#endregion
-export { CODE_FONT_FAMILY, DEFAULT_HIGHLIGHTER_LANGS, INKSTONE_DARK_THEME, INKSTONE_LIGHT_THEME, configureEditorSurface, configureHighlighter, getEditorSurface, getHighlighter, inkstoneRadius, inkstoneShadow, onigurumaEngine, shikiThemeId, surfacedTheme };
+export { CODE_FONT_FAMILY, DEFAULT_HIGHLIGHTER_LANGS, INKSTONE_DARK_THEME, INKSTONE_LIGHT_THEME, configureEditorColors, configureHighlighter, getEditorColors, getHighlighter, inkstoneRadius, inkstoneShadow, onigurumaEngine, shikiThemeId, withEditorColors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldsmirk/inkstone-core",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "Shared Shiki highlighter service for the inkstone editor toolkit: one fine-grained singleton (catppuccin themes, the JS regex engine by default or Oniguruma on request) reused by Monaco, static rendering, and markdown surfaces.",
   "keywords": [
     "shiki",