rune-lab 0.4.8 → 0.5.0-rc.2

package/dist/src/core/kernel/kernel.js

@@ -0,0 +1,157 @@
+import { Context, Effect, Option } from "effect";
+import { settingsSections } from "../forge/define-contribution.js";
+import { StateCellsTag } from "../services/layers.js";
+import { compileEnvironment } from "./wiring.js";
+export function createKernel(pluginsInput, options) {
+	const { runtime, resolvedPlugins, sortedSlots } = compileEnvironment(
+		pluginsInput,
+		options,
+	);
+	const ctx = runtime.runSync(Effect.context());
+	const cellsService = Context.get(ctx, StateCellsTag);
+	const cells = cellsService.cells;
+	const stores = extractStores(ctx, sortedSlots);
+	const overlays = extractOverlays(resolvedPlugins);
+	const initialContributions = extractInitialContributions(resolvedPlugins);
+	const registeredStores = new Map();
+	// Auto-register declarative contributions to matching stores by string ID matching (fallback)
+	for (const plugin of resolvedPlugins) {
+		if (plugin.contributions) {
+			for (const entry of plugin.contributions) {
+				const store = stores.get(entry.key.id);
+				if (store && typeof store.register === "function") {
+					entry.items.forEach((item) => store.register(item));
+				}
+			}
+		}
+	}
+	cells.contributions.set(initialContributions);
+	const slotMap = new Map(sortedSlots.map((s) => [s.id, s]));
+	function getCell(cellName) {
+		if (cellName === "contributions") {
+			return cells.contributions;
+		}
+		let storeKey = cellName;
+		if (!cellName.startsWith("rl:")) {
+			if (cellName.includes(".")) {
+				const lastDot = cellName.lastIndexOf(".");
+				const pluginId = cellName.slice(0, lastDot);
+				const slotName = cellName.slice(lastDot + 1);
+				storeKey = `rl:${pluginId}:${slotName}`;
+			}
+		}
+		const store = stores.get(storeKey);
+		if (!store) {
+			throw new Error(`[Kernel] Cell "${cellName}" does not exist`);
+		}
+		return store;
+	}
+	return {
+		stores,
+		overlays,
+		getCell: (cellName) => {
+			const cell = getCell(cellName);
+			return cell.get();
+		},
+		setCell: async (cellName, value) => {
+			const cell = getCell(cellName);
+			await cell.set(value);
+		},
+		subscribe: (cellName, listener) => {
+			const cell = getCell(cellName);
+			return cell.subscribe(listener);
+		},
+		getCellVersion: (cellName) => {
+			const cell = getCell(cellName);
+			return cell.getVersion();
+		},
+		getContributions: (key) => {
+			const registry = cells.contributions.get();
+			return registry.get(key) ?? [];
+		},
+		registerContribution: (key, item) => {
+			registerContributionLifecycle(cells, key, item);
+			const store = registeredStores.get(key);
+			if (store) {
+				store.register(item);
+			}
+		},
+		unregisterContribution: (key, id) =>
+			unregisterContributionLifecycle(cells, key, id),
+		registerStore: (key, store) => {
+			registeredStores.set(key, store);
+			const items = cells.contributions.get().get(key) ?? [];
+			items.forEach((item) => store.register(item));
+		},
+		getStoreEntry: (id) => slotMap.get(id),
+		dispose: () => runtime.dispose(),
+	};
+}
+function extractStores(ctx, slots) {
+	const stores = new Map();
+	for (const slot of slots) {
+		const storeTag = Context.GenericTag(slot.id);
+		const opt = Context.getOption(ctx, storeTag);
+		if (Option.isSome(opt) && opt.value !== null && opt.value !== undefined) {
+			stores.set(slot.id, opt.value);
+		}
+	}
+	return stores;
+}
+function extractOverlays(plugins) {
+	const overlays = [];
+	for (const plugin of plugins) {
+		if (plugin.overlays) {
+			overlays.push(...plugin.overlays);
+		}
+	}
+	return overlays;
+}
+function extractInitialContributions(plugins) {
+	const contributions = new Map();
+	for (const plugin of plugins) {
+		if (plugin.contributions) {
+			for (const entry of plugin.contributions) {
+				if (!contributions.has(entry.key)) {
+					contributions.set(entry.key, []);
+				}
+				contributions.get(entry.key)?.push(...entry.items);
+			}
+		}
+		// Automatically register settings schemas as contributions to "settingsSections"
+		if (plugin.settings) {
+			if (!contributions.has(settingsSections)) {
+				contributions.set(settingsSections, []);
+			}
+			contributions.get(settingsSections)?.push(plugin.settings);
+		}
+	}
+	return contributions;
+}
+function registerContributionLifecycle(cells, key, item) {
+	const contributionsCell = cells.contributions;
+	if (!contributionsCell) {
+		return;
+	}
+	const registry = new Map(contributionsCell.get());
+	const list = registry.get(key) ? [...registry.get(key)] : [];
+	list.push(item);
+	registry.set(key, list);
+	contributionsCell.set(registry);
+}
+function unregisterContributionLifecycle(cells, key, id) {
+	const contributionsCell = cells.contributions;
+	if (!contributionsCell) {
+		return;
+	}
+	const registry = new Map(contributionsCell.get());
+	const list = registry.get(key);
+	if (list) {
+		const filtered = list.filter((item) => {
+			const obj = item;
+			return !obj || obj.id !== id;
+		});
+		registry.set(key, filtered);
+		contributionsCell.set(registry);
+	}
+}

package/dist/src/core/kernel/wiring.d.ts

@@ -0,0 +1,39 @@
+import { ManagedRuntime } from "effect";
+import type { ForgedPlugin, PluginInput } from "../forge/define-plugin.js";
+import type { SlotContext } from "../forge/define-slot.js";
+import type { LocaleAdapter } from "../ports/locale.js";
+import type { PersistenceDriver } from "../ports/persistence.js";
+import type { TextMeasurer } from "../ports/text.js";
+export interface NormalizedSlot {
+	id: string;
+	slotName: string;
+	pluginId: string;
+	contextKey: symbol;
+	dependsOn: string[];
+	expose: boolean;
+	persist?: boolean | string[];
+	configSchema?: unknown;
+	create: (context: SlotContext<unknown>) => unknown;
+}
+export declare function resolveSlotRef(
+	ref: string,
+	declaringPluginId: string,
+	all: Map<string, NormalizedSlot>,
+): NormalizedSlot;
+export declare function normalizeSlots(
+	sorted: ForgedPlugin[],
+): NormalizedSlot[];
+type KernelRuntime = ManagedRuntime.ManagedRuntime<unknown, never>;
+export declare function compileEnvironment(
+	pluginsInput: PluginInput[],
+	options: {
+		config: Record<string, unknown>;
+		persistence: PersistenceDriver;
+		localeAdapter?: LocaleAdapter;
+		textMeasurer?: TextMeasurer;
+	},
+): {
+	runtime: KernelRuntime;
+	resolvedPlugins: ForgedPlugin[];
+	sortedSlots: NormalizedSlot[];
+};

package/dist/src/core/kernel/wiring.js

@@ -0,0 +1,253 @@
+import { Context, Effect, Layer, ManagedRuntime, Schema } from "effect";
+import { createInMemoryDriver } from "../persistence/memory.js";
+import {
+	makeLocaleAdapterLayer,
+	makePersistenceLayer,
+	makeStateCellsLayer,
+} from "../services/layers.js";
+import { topologicalSort } from "../utils/graph.js";
+
+function normalizePlugins(inputs) {
+	const flat = [];
+	function process(item) {
+		if (!item) {
+			return;
+		}
+		if (Array.isArray(item)) {
+			for (const sub of item) {
+				process(sub);
+			}
+		} else if (typeof item === "object") {
+			flat.push(item);
+		}
+	}
+	for (const item of inputs) {
+		process(item);
+	}
+	const seen = new Set();
+	return flat.filter((p) => {
+		if (seen.has(p.id)) {
+			return false;
+		}
+		seen.add(p.id);
+		return true;
+	});
+}
+function getPluginConfig(pluginId, config) {
+	if (config[pluginId] !== undefined) {
+		return config[pluginId];
+	}
+	return config;
+}
+function sortPlugins(resolved) {
+	const pluginMap = new Map(resolved.map((p) => [p.id, p]));
+	const graphNodes = resolved.map((p) => ({
+		id: p.id,
+		dependsOn: p.requires ?? [],
+	}));
+	for (const node of graphNodes) {
+		for (const reqId of node.dependsOn ?? []) {
+			if (!pluginMap.has(reqId)) {
+				throw new Error(
+					`[Kernel] Missing requirement: Plugin "${node.id}" requires "${reqId}", but "${reqId}" is not provided.`,
+				);
+			}
+		}
+	}
+	try {
+		const sortedNodes = topologicalSort(graphNodes);
+		return sortedNodes.map((node) => pluginMap.get(node.id));
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		throw new Error(`[Kernel] Circular dependency detected in plugins: ${msg}`);
+	}
+}
+export function resolveSlotRef(ref, declaringPluginId, all) {
+	const bareId = `rl:${declaringPluginId}:${ref}`;
+	if (all.has(bareId)) {
+		return all.get(bareId);
+	}
+	if (ref.includes(".")) {
+		const lastDot = ref.lastIndexOf(".");
+		const otherPluginId = ref.slice(0, lastDot);
+		const otherSlotName = ref.slice(lastDot + 1);
+		const dottedId = `rl:${otherPluginId}:${otherSlotName}`;
+		if (all.has(dottedId)) {
+			return all.get(dottedId);
+		}
+	}
+	throw new Error(
+		`[Kernel] Cannot resolve slot reference "${ref}" declared in plugin "${declaringPluginId}"`,
+	);
+}
+export function normalizeSlots(sorted) {
+	const allSlots = [];
+	const allSlotsMap = new Map();
+	for (const plugin of sorted) {
+		const slots = plugin.slots || {};
+		for (const [slotName, slotSpec] of Object.entries(slots)) {
+			const slotId = `rl:${plugin.id}:${slotName}`;
+			const descriptor = plugin.descriptors[slotName];
+			const slot = {
+				id: slotId,
+				slotName,
+				pluginId: plugin.id,
+				contextKey: descriptor.contextKey,
+				dependsOn: [],
+				expose: slotSpec.expose !== false,
+				persist: slotSpec.persist,
+				configSchema: slotSpec.config,
+				create: slotSpec.create,
+			};
+			allSlots.push(slot);
+			allSlotsMap.set(slotId, slot);
+		}
+	}
+	for (const plugin of sorted) {
+		const slots = plugin.slots || {};
+		for (const [slotName, slotSpec] of Object.entries(slots)) {
+			const slotId = `rl:${plugin.id}:${slotName}`;
+			const slot = allSlotsMap.get(slotId);
+			const resolvedDeps = [];
+			for (const dep of slotSpec.dependsOn ?? []) {
+				const resolvedSlot = resolveSlotRef(dep, plugin.id, allSlotsMap);
+				if (resolvedSlot.pluginId !== plugin.id) {
+					if (!plugin.requires?.includes(resolvedSlot.pluginId)) {
+						throw new Error(
+							`[Kernel] Invalid dependency: Slot "${slotName}" in plugin "${plugin.id}" depends on "${dep}", but "${resolvedSlot.pluginId}" is not in the requires spec of "${plugin.id}".`,
+						);
+					}
+				}
+				resolvedDeps.push(resolvedSlot.id);
+			}
+			slot.dependsOn = resolvedDeps;
+		}
+	}
+	return allSlots;
+}
+function sortSlots(slots) {
+	const slotGraphNodes = slots.map((s) => ({
+		id: s.id,
+		dependsOn: s.dependsOn,
+	}));
+	try {
+		const sortedSlotNodes = topologicalSort(slotGraphNodes);
+		return sortedSlotNodes.map((n) => slots.find((s) => s.id === n.id));
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		throw new Error(`[Kernel] Circular dependency detected in slots: ${msg}`);
+	}
+}
+function buildLayers(slots, options) {
+	const cellsLayer = makeStateCellsLayer({
+		contributions: new Map(),
+	});
+	let env = Layer.merge(makePersistenceLayer(options.persistence), cellsLayer);
+	if (options.localeAdapter) {
+		env = Layer.merge(env, makeLocaleAdapterLayer(options.localeAdapter));
+	}
+	for (const slot of slots) {
+		const storeTag = Context.GenericTag(slot.id);
+		const storeLayer = Layer.effect(
+			storeTag,
+			Effect.gen(function* () {
+				const pluginConfig = getPluginConfig(slot.pluginId, options.config);
+				let configSlice = pluginConfig;
+				if (slot.configSchema) {
+					try {
+						configSlice = Schema.decodeUnknownSync(slot.configSchema)(
+							pluginConfig,
+						);
+					} catch (err) {
+						const errMsg = err instanceof Error ? err.message : String(err);
+						throw new Error(
+							`[Kernel] Config validation failed for plugin "${slot.pluginId}", slot "${slot.slotName}": ${errMsg}`,
+						);
+					}
+				}
+				let persistenceHandle;
+				if (slot.persist) {
+					const prefix = `rl:${slot.pluginId}:${slot.slotName}:`;
+					persistenceHandle = {
+						get: (key) => options.persistence.get(`${prefix}${key}`),
+						set: (key, value) =>
+							options.persistence.set(`${prefix}${key}`, value),
+						remove: (key) => options.persistence.remove(`${prefix}${key}`),
+					};
+				} else {
+					const mem = createInMemoryDriver();
+					persistenceHandle = {
+						get: (key) => mem.get(key),
+						set: (key, value) => mem.set(key, value),
+						remove: (key) => mem.remove(key),
+					};
+				}
+				const resolvedDeps = new Map();
+				for (const depId of slot.dependsOn) {
+					const depTag = Context.GenericTag(depId);
+					const depStore = yield* depTag;
+					resolvedDeps.set(depId, depStore);
+					if (depId.startsWith("rl:")) {
+						const parts = depId.split(":");
+						resolvedDeps.set(parts[parts.length - 1], depStore);
+					}
+				}
+				let store = null;
+				try {
+					store = slot.create({
+						config: configSlice,
+						persistence: persistenceHandle,
+						stores: resolvedDeps,
+						locale: options.localeAdapter,
+						textMeasurer: options.textMeasurer,
+					});
+				} catch (e) {
+					console.error(`[Kernel] Failed to initialize slot "${slot.id}":`, e);
+					throw e;
+				}
+				if (store !== null && store !== undefined) {
+					const storeObj = store;
+					const hasDispose = typeof storeObj.dispose === "function";
+					if (hasDispose) {
+						yield* Effect.addFinalizer(() =>
+							Effect.tryPromise({
+								try: async () => {
+									const res = storeObj.dispose();
+									if (res instanceof Promise) {
+										await res;
+									}
+								},
+								catch: (e) => e,
+							}).pipe(
+								Effect.catchAll((e) =>
+									Effect.sync(() => {
+										console.error(
+											`[Kernel] Error disposing store ${slot.id}:`,
+											e,
+										);
+									}),
+								),
+							),
+						);
+					}
+				}
+				return store;
+			}),
+		);
+		env = Layer.provideMerge(storeLayer, env);
+	}
+	return env;
+}
+export function compileEnvironment(pluginsInput, options) {
+	const resolved = normalizePlugins(pluginsInput);
+	const sortedPlugins = sortPlugins(resolved);
+	const slots = normalizeSlots(sortedPlugins);
+	const sortedSlots = sortSlots(slots);
+	const env = buildLayers(sortedSlots, options);
+	const runtime = ManagedRuntime.make(env);
+	return {
+		runtime,
+		resolvedPlugins: resolved,
+		sortedSlots,
+	};
+}

package/dist/src/core/mod.d.ts

@@ -0,0 +1,62 @@
+export { StateCell } from "./cells/define-cell.js";
+export { createPersistedCell } from "./cells/persisted-cell.js";
+export {
+	type ConfigStore,
+	ConfigStoreImpl,
+	type ConfigStoreOptions,
+} from "./config/config-store.js";
+export {
+	type ContributionEntry,
+	type ContributionKey,
+	contribute,
+	defineContribution,
+	type SettingsSectionContribution,
+	settingsSections,
+} from "./forge/define-contribution.js";
+export type { PluginInput } from "./forge/define-plugin.js";
+export { definePlugin, type ForgedPlugin } from "./forge/define-plugin.js";
+export {
+	defineSettings,
+	type SettingsFieldSchema,
+	type SettingsSchema,
+} from "./forge/define-settings.js";
+export type {
+	BaseSlotSpec,
+	SlotContext,
+	SlotSpec,
+} from "./forge/define-slot.js";
+export { defineSlot } from "./forge/define-slot.js";
+export type { PersistenceHandle, SlotDescriptor } from "./forge/descriptors.js";
+export { getContextSymbol } from "./forge/descriptors.js";
+export { createKernel, type Kernel } from "./kernel/kernel.js";
+export type { LocaleAdapter } from "./ports/locale.js";
+export {
+	createInMemoryDriver,
+	inMemoryDriver,
+	namespaced,
+} from "./ports/memory.js";
+export type { PersistenceDriver } from "./ports/persistence.js";
+export type {
+	LayoutCursor,
+	LayoutLine,
+	LayoutLineRange,
+	LayoutLinesResult,
+	LayoutResult,
+	LineStats,
+	PreparedRichInline,
+	PreparedText,
+	PreparedTextWithSegments,
+	PrepareOptions,
+	RichInlineCursor,
+	RichInlineFragment,
+	RichInlineFragmentRange,
+	RichInlineItem,
+	RichInlineLine,
+	RichInlineLineRange,
+	RichInlineStats,
+	TextMeasurer,
+	WhiteSpaceMode,
+	WordBreakMode,
+} from "./ports/text.js";
+export { FakeTextMeasurer } from "./ports/text-fake.js";
+export type { StateCells } from "./services/layers.js";

package/dist/src/core/mod.js

@@ -0,0 +1,19 @@
+export { StateCell } from "./cells/define-cell.js";
+export { createPersistedCell } from "./cells/persisted-cell.js";
+export { ConfigStoreImpl } from "./config/config-store.js";
+export {
+	contribute,
+	defineContribution,
+	settingsSections,
+} from "./forge/define-contribution.js";
+export { definePlugin } from "./forge/define-plugin.js";
+export { defineSettings } from "./forge/define-settings.js";
+export { defineSlot } from "./forge/define-slot.js";
+export { getContextSymbol } from "./forge/descriptors.js";
+export { createKernel } from "./kernel/kernel.js";
+export {
+	createInMemoryDriver,
+	inMemoryDriver,
+	namespaced,
+} from "./ports/memory.js";
+export { FakeTextMeasurer } from "./ports/text-fake.js";

package/dist/src/core/persistence/memory.d.ts

@@ -0,0 +1 @@
+export * from "../ports/memory.js";

package/dist/src/core/persistence/memory.js

@@ -0,0 +1 @@
+export * from "../ports/memory.js";

package/dist/src/core/ports/locale.d.ts

@@ -0,0 +1,5 @@
+export interface LocaleAdapter {
+	getLocale(): string;
+	setLocale(locale: string): void | Promise<void>;
+	onChange(callback: (locale: string) => void): () => void;
+}

package/dist/src/core/ports/memory.d.ts

@@ -0,0 +1,7 @@
+import type { PersistenceDriver } from "./persistence.js";
+export declare function createInMemoryDriver(): PersistenceDriver;
+export declare const inMemoryDriver: PersistenceDriver;
+export declare function namespaced(
+	driver: PersistenceDriver,
+	prefix: string,
+): PersistenceDriver;

package/dist/src/core/ports/memory.js

@@ -0,0 +1,20 @@
+export function createInMemoryDriver() {
+	const store = new Map();
+	return {
+		get: (key) => store.get(key) ?? null,
+		set: (key, value) => {
+			store.set(key, value);
+		},
+		remove: (key) => {
+			store.delete(key);
+		},
+	};
+}
+export const inMemoryDriver = createInMemoryDriver();
+export function namespaced(driver, prefix) {
+	return {
+		get: (key) => driver.get(`${prefix}${key}`),
+		set: (key, value) => driver.set(`${prefix}${key}`, value),
+		remove: (key) => driver.remove(`${prefix}${key}`),
+	};
+}

package/dist/src/core/ports/persistence.d.ts

@@ -0,0 +1,5 @@
+export interface PersistenceDriver {
+	get(key: string): string | null | Promise<string | null>;
+	set(key: string, value: string): void | Promise<void>;
+	remove(key: string): void | Promise<void>;
+}

package/dist/src/core/ports/text-fake.d.ts

@@ -0,0 +1,83 @@
+import type {
+	LayoutCursor,
+	LayoutLine,
+	LayoutLineRange,
+	LayoutLinesResult,
+	LineStats,
+	PreparedRichInline,
+	PreparedText,
+	PreparedTextWithSegments,
+	PrepareOptions,
+	RichInlineCursor,
+	RichInlineItem,
+	RichInlineLine,
+	RichInlineLineRange,
+	RichInlineStats,
+	TextMeasurer,
+} from "./text.js";
+export declare class FakeTextMeasurer implements TextMeasurer {
+	prepare(text: string, font: string, options?: PrepareOptions): PreparedText;
+	prepareWithSegments(
+		text: string,
+		font: string,
+		options?: PrepareOptions,
+	): PreparedTextWithSegments;
+	layout(
+		prepared: PreparedText,
+		maxWidth: number,
+		lineHeight: number,
+	): {
+		lineCount: number;
+		height: number;
+	};
+	materializeLineRange(
+		prepared: PreparedTextWithSegments,
+		line: LayoutLineRange,
+	): LayoutLine;
+	walkLineRanges(
+		prepared: PreparedTextWithSegments,
+		maxWidth: number,
+		onLine: (line: LayoutLineRange) => void,
+	): number;
+	measureLineStats(
+		prepared: PreparedTextWithSegments,
+		maxWidth: number,
+	): LineStats;
+	measureNaturalWidth(prepared: PreparedTextWithSegments): number;
+	layoutNextLine(
+		prepared: PreparedTextWithSegments,
+		start: LayoutCursor,
+		maxWidth: number,
+	): LayoutLine | null;
+	layoutNextLineRange(
+		prepared: PreparedTextWithSegments,
+		start: LayoutCursor,
+		maxWidth: number,
+	): LayoutLineRange | null;
+	layoutWithLines(
+		prepared: PreparedTextWithSegments,
+		maxWidth: number,
+		lineHeight: number,
+	): LayoutLinesResult;
+	clearCache(): void;
+	setLocale(_locale?: string): void;
+	prepareRichInline(items: RichInlineItem[]): PreparedRichInline;
+	layoutNextRichInlineLineRange(
+		prepared: PreparedRichInline,
+		maxWidth: number,
+		start?: RichInlineCursor,
+	): RichInlineLineRange | null;
+	materializeRichInlineLineRange(
+		prepared: PreparedRichInline,
+		line: RichInlineLineRange,
+	): RichInlineLine;
+	walkRichInlineLineRanges(
+		prepared: PreparedRichInline,
+		maxWidth: number,
+		onLine: (line: RichInlineLineRange) => void,
+	): number;
+	measureRichInlineStats(
+		prepared: PreparedRichInline,
+		maxWidth: number,
+	): RichInlineStats;
+}