@coldsmirk/inkstone-core 0.18.0 → 0.19.0

package/README.md

@@ -9,7 +9,9 @@ Part of [inkstone](https://github.com/coldsmirk/inkstone). The editor layers ([`
 - **`getHighlighter()`** — the process-wide `HighlighterCore` promise. JavaScript / TypeScript / JSON / SQL grammars and the catppuccin theme pair load by default.
 - **`configureHighlighter(config)`** — extend or replace the default grammar / theme set, once, before any editor mounts. `DEFAULT_HIGHLIGHTER_LANGS` is exported so extension is additive.
 - **`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 the editors' own surfaces in your design language, once, before any editor mounts: per-scheme CSS color literals for `background` (content and gutter), `lineHighlight`, `lineNumber`, `widget` (completion, hover, parameter hints, the find widget and search panels), `widgetBorder`, and `widgetSelection`. The catppuccin pair keeps its syntax palette 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 color literals (a `var()` reference is refused — Monaco cannot resolve one). Keep `lineHighlight` translucent: CodeMirror draws selections behind the content, so an opaque active line would hide them. `getEditorSurface(dark)` reads what was configured.
 - **`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.
 
 ## Install
 
@@ -22,12 +24,18 @@ pnpm add @coldsmirk/inkstone-core
 ## Quick start
 
 ```ts
-import { configureHighlighter, DEFAULT_HIGHLIGHTER_LANGS, getHighlighter, shikiThemeId } from "@coldsmirk/inkstone-core";
+import { configureEditorSurface, configureHighlighter, DEFAULT_HIGHLIGHTER_LANGS, getHighlighter, shikiThemeId } from "@coldsmirk/inkstone-core";
 import yaml from "@shikijs/langs/yaml";
 
 // Optional: add grammars/themes beyond the defaults — once, before any editor mounts.
 configureHighlighter({ langs: [...DEFAULT_HIGHLIGHTER_LANGS, yaml] });
 
+// Optional: paint the editors' surfaces in your own tokens (syntax colors stay catppuccin's).
+configureEditorSurface({
+  light: { background: "#f7f7fa", lineHighlight: "#ffffff", widget: "#ffffff", widgetBorder: "#ced4da" },
+  dark: { background: "#1d1b22", lineHighlight: "#232129", widget: "#302e38", widgetBorder: "#423f4b" }
+});
+
 const highlighter = await getHighlighter();
 const html = highlighter.codeToHtml("const x = 1;", {
   lang: "javascript",
@@ -37,6 +45,16 @@ const html = highlighter.codeToHtml("const x = 1;", {
 
 The same instance is the right one for non-editor surfaces (markdown code blocks, JSON inspectors, Mantine's `@mantine/code-highlight` adapter) — sharing it keeps their colors identical to the editors'.
 
+Corners and elevation are CSS tokens rather than configuration — declare them once and both engines follow:
+
+```css
+:root {
+  --inkstone-radius-medium: 8px; /* menu rows, completion rows */
+  --inkstone-radius-large: 8px; /* the floating widgets themselves */
+  --inkstone-shadow-large: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+```
+
 ## License
 
 UNLICENSED — proprietary. All rights reserved; no use, copying, or redistribution without the author's permission.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { HighlighterCore, HighlighterCore as HighlighterCore$1, LanguageInput, ThemeInput } from "shiki/core";
+import { HighlighterCore, HighlighterCore as HighlighterCore$1, LanguageInput, ThemeInput, ThemeRegistration } from "shiki/core";
 //#region src/code-font.d.ts
 /**
  * The code font stack every inkstone editor host renders with: the page's
@@ -8,6 +8,81 @@ import { HighlighterCore, HighlighterCore as HighlighterCore$1, LanguageInput, T
  */
 declare const CODE_FONT_FAMILY = "var(--inkstone-font-family-code, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace)";
 //#endregion
+//#region src/surface.d.ts
+/**
+ * The surfaces an editor paints, 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, the floating completion / hover / find widgets —
+ * in its own tokens, so an editor sits inside the app instead of bringing a second dark.
+ *
+ * Every value is a CSS color literal (`#rrggbb`, `rgb(…)`): Monaco resolves its theme colors
+ * itself and cannot follow a custom property. An omitted role keeps the flavor's own color.
+ */
+interface EditorSurface {
+  /**
+   * The editor's own background: the content area and the gutter.
+   */
+  background?: string;
+  /**
+   * The current line's highlight. Prefer a translucent color: CodeMirror draws selections
+   * behind the content, so an opaque fill on the active line hides a selection there (Monaco
+   * paints selections above it and is indifferent).
+   */
+  lineHighlight?: string;
+  /**
+   * Line numbers.
+   */
+  lineNumber?: string;
+  /**
+   * Floating chrome: completion, hover and parameter hints, the find widget and the search
+   * panels.
+   */
+  widget?: string;
+  /**
+   * The hairline around floating chrome and its fields.
+   */
+  widgetBorder?: string;
+  /**
+   * A hovered or selected row inside floating chrome.
+   */
+  widgetSelection?: string;
+}
+/**
+ * One surface per color scheme; an omitted scheme keeps the flavor's own surfaces.
+ */
+interface EditorSurfaces {
+  light?: EditorSurface;
+  dark?: EditorSurface;
+}
+/**
+ * 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
+ * editor never defines — its chrome ships square by omission), CodeMirror's chrome polish
+ * reads them directly; each falls back to the look it ships with when the host sets none.
+ */
+type RadiusSize = "small" | "medium" | "large" | "xlarge";
+/**
+ * A `var()` reference to the host's `--inkstone-radius-<size>` token with the given fallback.
+ */
+declare function inkstoneRadius(size: RadiusSize, fallback: string): string;
+/**
+ * The elevation sizes floating chrome reads from the host: `--inkstone-shadow-<size>`, a full
+ * `box-shadow` value. Same contract as the radii: Monaco maps them onto VS Code's
+ * `--vscode-shadow-*` tokens, CodeMirror's tooltips read them directly, each with its own
+ * fallback.
+ */
+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
 /**
  * Shiki theme id inkstone editors use in light mode.
@@ -41,6 +116,23 @@ interface HighlighterConfig {
  * {@link getHighlighter} call — afterwards the instance is already built and this throws.
  */
 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.
+ *
+ * Every value must be a CSS color literal — Monaco resolves theme colors itself, so a custom
+ * property reference would silently paint the wrong color; it is refused here instead.
+ */
+declare function configureEditorSurface(surfaces: EditorSurfaces): void;
+/**
+ * The surface configured for a color scheme through {@link configureEditorSurface}, or
+ * undefined when the flavor's own surfaces stand.
+ */
+declare function getEditorSurface(dark: boolean): EditorSurface | undefined;
 /**
  * The shared Shiki highlighter, built lazily on first call.
  *
@@ -60,4 +152,4 @@ declare function getHighlighter(): Promise<HighlighterCore$1>;
  */
 declare function shikiThemeId(dark: boolean): string;
 //#endregion
-export { CODE_FONT_FAMILY, DEFAULT_HIGHLIGHTER_LANGS, type HighlighterConfig, type HighlighterCore, INKSTONE_DARK_THEME, INKSTONE_LIGHT_THEME, configureHighlighter, getHighlighter, shikiThemeId };
+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, shikiThemeId, surfacedTheme };

package/dist/index.js

@@ -9,6 +9,63 @@ import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
 //#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 = {
+	background: [
+		"editor.background",
+		"editorGutter.background",
+		"editorCursor.background",
+		"editorOverviewRuler.background",
+		"editorGroup.emptyBackground",
+		"editorStickyScroll.background",
+		"minimap.background",
+		"input.background"
+	],
+	lineHighlight: ["editor.lineHighlightBackground", "editorStickyScrollHover.background"],
+	lineNumber: ["editorLineNumber.foreground"],
+	widget: [
+		"editorWidget.background",
+		"editorSuggestWidget.background",
+		"editorHoverWidget.background",
+		"dropdown.background"
+	],
+	widgetBorder: [
+		"editorWidget.border",
+		"editorWidget.resizeBorder",
+		"editorSuggestWidget.border",
+		"editorHoverWidget.border",
+		"dropdown.border"
+	],
+	widgetSelection: [
+		"editorSuggestWidget.selectedBackground",
+		"list.activeSelectionBackground",
+		"list.inactiveSelectionBackground",
+		"list.focusBackground",
+		"list.hoverBackground"
+	]
+};
+function surfacedTheme(theme, surface) {
+	const roles = Object.entries(SURFACE_COLORS);
+	const colors = { ...theme.colors };
+	let changed = false;
+	for (const [role, keys] of roles) {
+		const value = surface?.[role];
+		if (value === void 0) continue;
+		for (const key of keys) colors[key] = value;
+		changed = true;
+	}
+	return changed ? {
+		...theme,
+		colors
+	} : theme;
+}
+//#endregion
 //#region src/shiki.ts
 const INKSTONE_LIGHT_THEME = "catppuccin-latte";
 const INKSTONE_DARK_THEME = "catppuccin-macchiato";
@@ -25,28 +82,49 @@ function getHighlighterRegistry() {
 	if (!registry) {
 		registry = {
 			config: {},
+			surfaces: {},
 			promise: null
 		};
 		host[HIGHLIGHTER_REGISTRY_KEY] = registry;
 	}
+	registry.surfaces ??= {};
 	return registry;
 }
+function assertConfigurable(registry, caller) {
+	if (registry.promise) throw new Error(`${caller} must be called before the first getHighlighter()`);
+}
 function configureHighlighter(options) {
 	const registry = getHighlighterRegistry();
-	if (registry.promise) throw new Error("configureHighlighter must be called before the first getHighlighter()");
+	assertConfigurable(registry, "configureHighlighter");
 	registry.config = {
 		...registry.config,
 		...options
 	};
 }
+function configureEditorSurface(surfaces) {
+	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" && value.includes("var(")) throw new Error(`configureEditorSurface: ${scheme}.${role} must be a CSS color literal, not a custom property reference (${value})`);
+	}
+	registry.surfaces = {
+		...registry.surfaces,
+		...surfaces
+	};
+}
+function getEditorSurface(dark) {
+	const { surfaces } = getHighlighterRegistry();
+	return dark ? surfaces.dark : surfaces.light;
+}
 function getHighlighter() {
 	const registry = getHighlighterRegistry();
 	const existing = registry.promise;
 	if (existing) return existing;
 	const attempt = createHighlighterCore({
 		themes: [
-			catppuccinLatte,
-			catppuccinMacchiato,
+			surfacedTheme(catppuccinLatte, registry.surfaces.light),
+			surfacedTheme(catppuccinMacchiato, registry.surfaces.dark),
 			...registry.config.themes ?? []
 		],
 		langs: registry.config.langs ?? [...DEFAULT_HIGHLIGHTER_LANGS],
@@ -62,4 +140,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, configureHighlighter, getHighlighter, shikiThemeId };
+export { CODE_FONT_FAMILY, DEFAULT_HIGHLIGHTER_LANGS, INKSTONE_DARK_THEME, INKSTONE_LIGHT_THEME, configureEditorSurface, configureHighlighter, getEditorSurface, getHighlighter, inkstoneRadius, inkstoneShadow, shikiThemeId, surfacedTheme };

package/package.json

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