rune-lab 0.4.8 → 0.5.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Bryan Reza Campos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/Yrrrrrf/rune-lab/refs/heads/main/apps/lab/src/lib/assets/img/rune.png" alt="Rune Lab Icon" width="128" height="128" description="Icon representing the Svelte Runes system">
+  <div align="center">Rune Lab</div>
+</h1>
+
+<div align="center">
+
+[![JSR](https://jsr.io/badges/@yrrrrrf/rune-lab)](https://jsr.io/@yrrrrrf/rune-lab)
+[![NPM Package](https://img.shields.io/npm/v/rune-lab.svg)](https://www.npmjs.com/package/rune-lab)
+[![GitHub](https://img.shields.io/badge/GitHub-Yrrrrrf%2Frune--lab-blue)](https://github.com/Yrrrrrf/rune-lab)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://choosealicense.com/licenses/mit/)
+
+</div>
+
+## Overview
+
+**Rune Lab** is a modern, extensible **plugin-based UI shell** for **Svelte 5**
+applications. Harnessing the power of Svelte's new **Runes** system, it provides
+a complete application skeleton with layout management, dynamic theming, i18n,
+keyboard shortcuts, a command palette, toast notifications, and currency
+controls.
+
+Everything is wired through a centralized **Provider + Registry + Context**
+architecture, ensuring clean dependency injection and state isolation across
+your app.
+
+## Installation
+
+```bash
+npm install rune-lab
+# or
+bun install rune-lab
+```
+
+## Setup & Quick Start
+
+Configure your application layout with the plugins. Here is what you need to set
+up in your root `+layout.svelte`:
+
+```svelte
+<script lang="ts">
+import "./layout.css";
+import { RuneProvider, version } from "rune-lab";
+import { I18nPlugin } from "rune-lab/i18n";
+import { LayoutPlugin } from "rune-lab/layout";
+import { PalettesPlugin } from "rune-lab/palettes";
+import type { Snippet } from "svelte";
+import AppLayout from "./AppLayout.svelte";
+
+import faviconUrl from "$lib/static/img/rune.png";
+
+let { children }: { children: Snippet } = $props();
+</script>
+
+<RuneProvider
+  config={{
+    favicon: faviconUrl,
+    icons: "material",
+    app: {
+      name: "Rune Lab",
+      version: version(),
+      description: "Plugin test bench",
+      author: "Yrrrrrf",
+    },
+    // Namespaced per-plugin config
+    "rune-lab.layout": "dark",
+  }}
+  plugins={[LayoutPlugin, PalettesPlugin, I18nPlugin]}
+>
+  <AppLayout>
+    {@render children()}
+  </AppLayout>
+</RuneProvider>
+```
+
+## Plugins
+
+Rune Lab is modular. Plugins are documented in their respective directories:
+
+- **Layout Plugin (`rune-lab/layout`)**:
+- **Palettes Plugin (`rune-lab/palettes`)**:
+- **i18n Plugin (`rune-lab/i18n`)**:
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.

package/dist/src/core/cells/define-cell.d.ts

@@ -0,0 +1,13 @@
+import { SubscriptionRef } from "effect";
+export declare class StateCell<T> {
+	ref: SubscriptionRef.SubscriptionRef<T>;
+	version: number;
+	private listeners;
+	constructor(ref: SubscriptionRef.SubscriptionRef<T>);
+	get(): T;
+	set(value: T): void;
+	getVersion(): number;
+	subscribe(listener: () => void): () => void;
+	private pendingNotify;
+	notify(): void;
+}

package/dist/src/core/cells/define-cell.js

@@ -0,0 +1,42 @@
+import { Effect, SubscriptionRef } from "effect";
+export class StateCell {
+	ref;
+	version = 0;
+	listeners = new Set();
+	constructor(ref) {
+		this.ref = ref;
+	}
+	get() {
+		return Effect.runSync(SubscriptionRef.get(this.ref));
+	}
+	set(value) {
+		Effect.runSync(SubscriptionRef.set(this.ref, value));
+	}
+	getVersion() {
+		return this.version;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	pendingNotify = false;
+	notify() {
+		this.version++;
+		if (this.pendingNotify) {
+			return;
+		}
+		this.pendingNotify = true;
+		queueMicrotask(() => {
+			this.pendingNotify = false;
+			for (const listener of this.listeners) {
+				try {
+					listener();
+				} catch (e) {
+					console.error(`[StateCell] Listener error:`, e);
+				}
+			}
+		});
+	}
+}

package/dist/src/core/cells/persisted-cell.d.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+import type { PersistenceHandle } from "../forge/descriptors.js";
+import { StateCell } from "./define-cell.js";
+export declare function createPersistedCell<T, TEncoded = T>(
+	schema: Schema.Schema<T, TEncoded, never>,
+	handle: PersistenceHandle,
+	initialValue: T,
+	key?: string,
+): StateCell<T>;

package/dist/src/core/cells/persisted-cell.js

@@ -0,0 +1,57 @@
+import { Effect, Schema, SubscriptionRef } from "effect";
+import { StateCell } from "./define-cell.js";
+export function createPersistedCell(schema, handle, initialValue, key = "") {
+	const ref = SubscriptionRef.make(initialValue).pipe(Effect.runSync);
+	const cell = new StateCell(ref);
+	const applyValue = (val) => {
+		if (val !== null && val !== undefined) {
+			try {
+				const parsed = JSON.parse(val);
+				const decoded = Schema.decodeUnknownSync(schema)(parsed);
+				cell.set(decoded);
+			} catch {
+				try {
+					const decoded = Schema.decodeUnknownSync(schema)(val);
+					cell.set(decoded);
+				} catch {
+					// ignore decoding errors, keep initial value
+				}
+			}
+		}
+	};
+	const saved = handle.get(key);
+	if (saved instanceof Promise) {
+		saved.then(applyValue).catch(() => {});
+	} else {
+		applyValue(saved);
+	}
+	const originalSet = cell.set.bind(cell);
+	cell.set = (value) => {
+		const oldValue = cell.get();
+		originalSet(value);
+		try {
+			const encoded = Schema.encodeSync(schema)(value);
+			const stringValue =
+				typeof encoded === "string" ? encoded : JSON.stringify(encoded);
+			const res = handle.set(key, stringValue);
+			if (res instanceof Promise) {
+				return res.catch((e) => {
+					originalSet(oldValue);
+					console.error(
+						`[PersistedCell] Failed to save value (reverted to old value):`,
+						e,
+					);
+					throw e;
+				});
+			}
+		} catch (e) {
+			originalSet(oldValue);
+			console.error(
+				`[PersistedCell] Failed to save value (reverted to old value):`,
+				e,
+			);
+			throw e;
+		}
+	};
+	return cell;
+}

package/dist/src/core/config/config-store.d.ts

@@ -0,0 +1,31 @@
+import type { PersistenceDriver } from "../ports/persistence.js";
+export type ConfigStore<T, K extends keyof T = keyof T> = {
+	current: T[K];
+	available: T[];
+	set(id: T[K]): void;
+	get(id: T[K]): T | undefined;
+	getProp<P extends keyof T>(prop: P, id?: T[K]): T[P] | undefined;
+	addItems(newItems: T[]): void;
+	onChange: (cb: (newId: T[K], oldId: T[K]) => void) => () => void;
+	setDriver: (driver: PersistenceDriver) => void;
+};
+export interface ConfigStoreOptions<T, K extends keyof T = keyof T> {
+	items: readonly T[];
+	storageKey: string;
+	displayName: string;
+	idKey: K;
+	icon?: string;
+	driver?: PersistenceDriver;
+}
+export declare class ConfigStoreImpl<T, K extends keyof T> {
+	#private;
+	current: T[K];
+	available: T[];
+	constructor(options: ConfigStoreOptions<T, K>);
+	setDriver(driver: PersistenceDriver): void;
+	set(id: T[K]): void;
+	onChange(cb: (newId: T[K], oldId: T[K]) => void): () => void;
+	get(id: T[K]): T | undefined;
+	getProp<P extends keyof T>(prop: P, id?: T[K]): T[P] | undefined;
+	addItems(newItems: T[]): void;
+}

package/dist/src/core/config/config-store.js

@@ -0,0 +1,79 @@
+import { createInMemoryDriver } from "../persistence/memory.js";
+export class ConfigStoreImpl {
+	current = null;
+	available = [];
+	#options;
+	#driver;
+	#callbacks = new Set();
+	constructor(options) {
+		this.#options = options;
+		const { items, idKey, driver = createInMemoryDriver() } = options;
+		this.#driver = driver;
+		this.available = [...items];
+		this.current = items[0][idKey];
+		this.#loadFromDriver(this.#driver);
+	}
+	#loadFromDriver(driver) {
+		const saved = driver.get(this.#options.storageKey);
+		if (saved instanceof Promise) {
+			saved
+				.then((val) => {
+					if (val && this.get(val)) {
+						const old = this.current;
+						this.current = val;
+						this.#notify(val, old);
+					}
+				})
+				.catch(() => {});
+		} else if (saved && this.get(saved)) {
+			this.current = saved;
+		}
+	}
+	setDriver(driver) {
+		this.#driver = driver;
+		this.#loadFromDriver(driver);
+	}
+	set(id) {
+		const item = this.get(id);
+		if (!item) {
+			console.warn(`${this.#options.displayName} "${id}" not found`);
+			return;
+		}
+		const old = this.current;
+		this.current = id;
+		this.#driver.set(this.#options.storageKey, String(id));
+		this.#notify(id, old);
+	}
+	#notify(newId, oldId) {
+		this.#callbacks.forEach((cb) => {
+			try {
+				cb(newId, oldId);
+			} catch (err) {
+				console.error(
+					`[rune-lab/core] Error in ${this.#options.displayName} onChange callback:`,
+					err,
+				);
+			}
+		});
+	}
+	onChange(cb) {
+		this.#callbacks.add(cb);
+		return () => this.#callbacks.delete(cb);
+	}
+	get(id) {
+		const idKey = this.#options.idKey;
+		return this.available.find((item) => item[idKey] === id);
+	}
+	getProp(prop, id) {
+		const targetId = id ?? this.current;
+		return this.get(targetId)?.[prop];
+	}
+	addItems(newItems) {
+		const idKey = this.#options.idKey;
+		for (const item of newItems) {
+			if (!this.get(item[idKey])) {
+				this.available.push(item);
+			}
+		}
+	}
+}

package/dist/src/core/forge/define-contribution.d.ts

@@ -0,0 +1,21 @@
+export interface ContributionKey<T> {
+	readonly id: string;
+	readonly __brand?: T;
+}
+export interface ContributionEntry<T = unknown> {
+	readonly key: ContributionKey<T>;
+	readonly items: T[];
+}
+export declare function defineContribution<T>(id: string): ContributionKey<T>;
+export declare function contribute<T>(
+	key: ContributionKey<T>,
+	...items: T[]
+): ContributionEntry<T>;
+export interface SettingsSectionContribution {
+	id: string;
+	label: string;
+	icon?: string;
+	fields?: unknown[];
+	component?: unknown;
+}
+export declare const settingsSections: ContributionKey<SettingsSectionContribution>;

package/dist/src/core/forge/define-contribution.js

@@ -0,0 +1,7 @@
+export function defineContribution(id) {
+	return { id };
+}
+export function contribute(key, ...items) {
+	return { key, items };
+}
+export const settingsSections = defineContribution("settingsSections");

package/dist/src/core/forge/define-plugin.d.ts

@@ -0,0 +1,33 @@
+import type { ContributionEntry } from "./define-contribution.js";
+import type { SettingsSchema } from "./define-settings.js";
+import type { BaseSlotSpec } from "./define-slot.js";
+import { type SlotDescriptor } from "./descriptors.js";
+export interface ForgedPlugin<
+	TId extends string = string,
+	TSlots extends Record<string, BaseSlotSpec> = Record<string, BaseSlotSpec>,
+> {
+	id: TId;
+	requires?: string[];
+	slots: TSlots;
+	settings?: SettingsSchema;
+	overlays?: unknown[];
+	contributions?: ContributionEntry<unknown>[];
+	descriptors: Record<keyof TSlots, SlotDescriptor>;
+}
+export type PluginInput =
+	| ForgedPlugin<string, Record<string, BaseSlotSpec>>
+	| PluginInput[]
+	| null
+	| undefined
+	| boolean;
+export declare function definePlugin<
+	TId extends string,
+	TSlots extends Record<string, BaseSlotSpec>,
+>(spec: {
+	id: TId;
+	requires?: string[];
+	slots?: TSlots;
+	settings?: SettingsSchema;
+	overlays?: unknown[];
+	contributions?: ContributionEntry<unknown>[];
+}): ForgedPlugin<TId, TSlots>;

package/dist/src/core/forge/define-plugin.js

@@ -0,0 +1,21 @@
+import { getAccessorName, getContextSymbol } from "./descriptors.js";
+export function definePlugin(spec) {
+	const slots = spec.slots || {};
+	const descriptors = {};
+	for (const slotName of Object.keys(slots)) {
+		descriptors[slotName] = {
+			slotName,
+			contextKey: getContextSymbol(spec.id, slotName),
+			accessorName: getAccessorName(slotName),
+		};
+	}
+	return {
+		id: spec.id,
+		requires: spec.requires,
+		slots: slots,
+		settings: spec.settings,
+		overlays: spec.overlays,
+		contributions: spec.contributions,
+		descriptors: descriptors,
+	};
+}

package/dist/src/core/forge/define-settings.d.ts

@@ -0,0 +1,33 @@
+export interface SettingsFieldSchema {
+	id: string;
+	label: string;
+	type: "select" | "toggle" | "text" | "number" | "range" | "color" | "custom";
+	component?: unknown;
+	options?: {
+		value: unknown;
+		label: string;
+	}[];
+	min?: number;
+	max?: number;
+	step?: number;
+	target:
+		| {
+				type: "cell";
+				name: string;
+		  }
+		| {
+				type: "store";
+				storeId: string;
+				property: string;
+		  }
+		| {
+				type: "callback";
+		  };
+}
+export interface SettingsSchema {
+	id: string;
+	label: string;
+	icon?: string;
+	fields: SettingsFieldSchema[];
+}
+export declare function defineSettings(schema: SettingsSchema): SettingsSchema;

package/dist/src/core/forge/define-settings.js

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+
+const TargetSchema = Schema.Union(
+	Schema.Struct({
+		type: Schema.Literal("cell"),
+		name: Schema.String,
+	}),
+	Schema.Struct({
+		type: Schema.Literal("store"),
+		storeId: Schema.String,
+		property: Schema.String,
+	}),
+	Schema.Struct({
+		type: Schema.Literal("callback"),
+	}),
+);
+const SettingsFieldSchemaStruct = Schema.Struct({
+	id: Schema.String,
+	label: Schema.String,
+	type: Schema.Literal(
+		"select",
+		"toggle",
+		"text",
+		"number",
+		"range",
+		"color",
+		"custom",
+	),
+	component: Schema.optional(Schema.Any),
+	options: Schema.optional(
+		Schema.Array(
+			Schema.Struct({
+				value: Schema.Any,
+				label: Schema.String,
+			}),
+		),
+	),
+	min: Schema.optional(Schema.Number),
+	max: Schema.optional(Schema.Number),
+	step: Schema.optional(Schema.Number),
+	target: TargetSchema,
+});
+const SettingsSchemaStruct = Schema.Struct({
+	id: Schema.String,
+	label: Schema.String,
+	icon: Schema.optional(Schema.String),
+	fields: Schema.Array(SettingsFieldSchemaStruct),
+});
+export function defineSettings(schema) {
+	const validated = Schema.decodeUnknownSync(SettingsSchemaStruct)(schema);
+	return Object.freeze(validated);
+}

package/dist/src/core/forge/define-slot.d.ts

@@ -0,0 +1,34 @@
+import type { Schema } from "effect";
+import type { LocaleAdapter } from "../ports/locale.js";
+import type { TextMeasurer } from "../ports/text.js";
+import type { PersistenceHandle } from "./descriptors.js";
+export interface SlotContext<TConfig = unknown> {
+	config: TConfig;
+	persistence: PersistenceHandle;
+	stores: Map<string, unknown>;
+	locale?: LocaleAdapter;
+	textMeasurer?: TextMeasurer;
+}
+export interface BaseSlotSpec {
+	create(context: SlotContext<unknown>): unknown;
+	config?: unknown;
+	persist?: boolean | string[];
+	dependsOn?: string[];
+	expose?: boolean;
+	contextKey?: never;
+}
+export interface SlotSpec<
+	TConfig = unknown,
+	TStore = unknown,
+	TEncoded = TConfig,
+> extends BaseSlotSpec {
+	create(context: SlotContext<TConfig>): TStore;
+	config?: Schema.Schema<TConfig, TEncoded, never>;
+	persist?: boolean | string[];
+	dependsOn?: string[];
+	expose?: boolean;
+	contextKey?: never;
+}
+export declare function defineSlot<TConfig, TStore, TEncoded = TConfig>(
+	spec: SlotSpec<TConfig, TStore, TEncoded>,
+): SlotSpec<TConfig, TStore, TEncoded>;

package/dist/src/core/forge/define-slot.js

@@ -0,0 +1,3 @@
+export function defineSlot(spec) {
+	return spec;
+}

package/dist/src/core/forge/descriptors.d.ts

@@ -0,0 +1,15 @@
+export interface SlotDescriptor {
+	slotName: string;
+	contextKey: symbol;
+	accessorName: string;
+}
+export interface PersistenceHandle {
+	get(key: string): string | null | Promise<string | null>;
+	set(key: string, value: string): void | Promise<void>;
+	remove(key: string): void | Promise<void>;
+}
+export declare function getAccessorName(slotName: string): string;
+export declare function getContextSymbol(
+	pluginId: string,
+	slotName: string,
+): symbol;

package/dist/src/core/forge/descriptors.js

@@ -0,0 +1,9 @@
+export function getAccessorName(slotName) {
+	if (!slotName) {
+		return "";
+	}
+	return `get${slotName.charAt(0).toUpperCase()}${slotName.slice(1)}Store`;
+}
+export function getContextSymbol(pluginId, slotName) {
+	return Symbol.for(`rl:${pluginId}:${slotName}`);
+}

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

@@ -0,0 +1,38 @@
+import { type ContributionKey } from "../forge/define-contribution.js";
+import type { PluginInput } from "../forge/define-plugin.js";
+import type { LocaleAdapter } from "../ports/locale.js";
+import type { PersistenceDriver } from "../ports/persistence.js";
+import type { TextMeasurer } from "../ports/text.js";
+export interface Kernel<TCells = Record<string, unknown>> {
+	stores: Map<string, unknown>;
+	overlays: unknown[];
+	getCell<K extends keyof TCells>(cellName: K): TCells[K];
+	setCell<K extends keyof TCells>(cellName: K, value: TCells[K]): Promise<void>;
+	subscribe(cellName: keyof TCells, listener: () => void): () => void;
+	getCellVersion(cellName: keyof TCells): number;
+	getContributions<T>(key: ContributionKey<T>): T[];
+	registerContribution<T>(key: ContributionKey<T>, item: T): void;
+	unregisterContribution<T>(key: ContributionKey<T>, id: string): void;
+	registerStore<T>(
+		key: ContributionKey<T>,
+		store: {
+			register(item: T): void;
+		},
+	): void;
+	getStoreEntry(id: string):
+		| {
+				contextKey?: symbol;
+				expose?: boolean;
+		  }
+		| undefined;
+	dispose(): Promise<void>;
+}
+export declare function createKernel<TCells = Record<string, unknown>>(
+	pluginsInput: PluginInput[],
+	options: {
+		config: Record<string, unknown>;
+		persistence: PersistenceDriver;
+		localeAdapter?: LocaleAdapter;
+		textMeasurer?: TextMeasurer;
+	},
+): Kernel<TCells>;