rune-lab 0.5.0-rc.1 → 0.5.0

package/README.md

@@ -1,5 +1,5 @@
 <h1 align="center">
-  <img src="https://raw.githubusercontent.com/Yrrrrrf/rune-lab/refs/heads/main/src/package/src/static/img/rune.png" alt="Rune Lab Icon" width="128" height="128" description="Icon representing the Svelte Runes system">
+  <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>
 
@@ -16,293 +16,70 @@
 
 **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 built-in layout management, dynamic
-theming, i18n, keyboard shortcuts, a command palette, toast notifications, and a
-highly precise money/currency subsystem.
+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.
 
-## Key Features
-
-- **✨ Svelte 5 Runes-First:** Built from the ground up using `$state`,
-  `$derived`, and `$effect`. No legacy Svelte 4 stores.
-- **🧩 Extensible Plugin Architecture:** Features are isolated into plugins
-  (`LayoutPlugin`, `PalettesPlugin`, `MoneyPlugin`). Only load what you need.
-- **🎨 Dynamic Theming & i18n:** 32 DaisyUI themes and 13 pre-configured locales
-  powered by Paraglide JS, with zero-flash SSR persistence.
-- **🔗 Declarative Callbacks:** Bridge store changes (theme, language, currency)
-  to your own system hooks via `RuneProvider` props.
-- **💾 Abstract Persistence Layer:** Swap between cookies, localStorage,
-  sessionStorage, or in-memory state seamlessly via generic drivers.
-- **💸 Robust Money Subsystem:** Backed by Dinero.js for floating-point-safe
-  precision arithmetic, complete with exchange rate strategies and masked
-  currency inputs.
-- **⌨️ Developer & Power-User Friendly:** Out-of-the-box Command Palette
-  (`Ctrl+K`) and interactive Shortcuts Palette (`Ctrl+/`).
-
 ## Installation
 
-### Using NPM / Bun
-
 ```bash
 npm install rune-lab
 # or
 bun install rune-lab
 ```
 
-## Project Configuration (Required)
-
-After installing, two configuration steps are required to ensure the framework's
-components are compiled and styled correctly in your consuming project.
-
-### Step 1 — Vite: Process `rune-lab` through the Svelte compiler
-
-By default, Vite externalizes `node_modules` during SSR, bypassing the Svelte
-compiler. Add the following to your `vite.config.ts` to process `rune-lab`
-properly:
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import { sveltekit } from "@sveltejs/kit/vite";
-
-export default defineConfig({
-  plugins: [sveltekit()],
-  ssr: {
-    noExternal: ["rune-lab"], // 👈 CRITICAL for Svelte 5 components in node_modules
-  },
-});
-```
-
-### Step 2 — Tailwind CSS v4: Scan `rune-lab` for utility classes
+## Setup & Quick Start
 
-Tailwind only generates CSS for classes it finds by scanning your source files.
-Add a `@source` directive to your project's main CSS file so Tailwind compiles
-the DaisyUI classes used internally by `rune-lab`:
-
-```css
-/* app.css / layout.css / global.css */
-@import "tailwindcss";
-@source "../node_modules/rune-lab/dist"; /* 👈 add this */
-```
-
-## Quick Start
-
-Get your application shell running in less than 40 lines. Inside your
-`+layout.svelte`:
+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 {
-  ConnectedNavigationPanel,
-  cookieDriver,
-  LayoutPlugin,
-  PalettesPlugin,
-  RuneProvider,
-  WorkspaceLayout,
-} from "rune-lab";
-import type { NavigationSection } from "rune-lab";
-import { setLocale } from "$lib/i18n/paraglide/runtime.js";
+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";
 
-let { children } = $props();
+import faviconUrl from "$lib/static/img/rune.png";
 
-const sections: NavigationSection[] = [
-  {
-    id: "main",
-    title: "Main Menu",
-    items: [
-      { id: "home", label: "Dashboard", icon: "🏠" },
-      { id: "settings", label: "Settings", icon: "⚙️" },
-    ],
-  },
-];
+let { children }: { children: Snippet } = $props();
 </script>
 
-<!-- Initialize the system with your required plugins and callbacks -->
 <RuneProvider
   config={{
-    app: { name: "My Startup", version: "1.0.0" },
-    persistence: cookieDriver,
-  }}
-  plugins={[LayoutPlugin, PalettesPlugin]}
-  onLanguageChange={(l) => setLocale(l.code)}
-  onThemeChange={(t) => console.log(`Theme changed to ${t.name}`)}
->
-  <WorkspaceLayout>
-    {#snippet navigationPanel()}
-      <!-- Auto-wires to LayoutStore state -->
-      <ConnectedNavigationPanel {sections} />
-    {/snippet}
-
-    {#snippet content()}
-      <div class="p-8">
-        {@render children()}
-      </div>
-    {/snippet}
-  </WorkspaceLayout>
-</RuneProvider>
-```
-
-You now have a fully reactive layout, a keyboard command palette, a toast
-notification system, and theme/language switchers.
-
-## Money & Currency Plugin
-
-Rune Lab provides a robust money layer that handles precision arithmetic,
-formatting, and live exchange-rate triangulation. To use it, simply register the
-`MoneyPlugin`:
-
-```svelte
-<script lang="ts">
-import { MoneyPlugin } from "rune-lab";
-</script>
-
-<RuneProvider
-  config={{
-    "rune-lab.money": {
-      defaultCurrency: "USD",
-      exchangeRates: {
-        base: "USD",
-        rates: { MXN: 17.23, EUR: 0.91 },
-      },
+    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, MoneyPlugin]}
+  plugins={[LayoutPlugin, PalettesPlugin, I18nPlugin]}
 >
-  <!-- App Content -->
+  <AppLayout>
+    {@render children()}
+  </AppLayout>
 </RuneProvider>
 ```
 
-### Displaying & Inputting Money
-
-```svelte
-<script lang="ts">
-import { CurrencySelector, MoneyDisplay, MoneyInput, useMoney } from "rune-lab";
-
-let price = $state(15000); // Minor units (e.g., cents) -> $150.00
-const { convert, format } = useMoney();
-</script>
-
-<!-- Select from available currencies -->
-<CurrencySelector />
-
-<!-- Formats safely and localizes based on the active LanguageStore -->
-<MoneyDisplay amount={price} currency="USD" />
-
-<!-- Compact notation ($1.5M) -->
-<MoneyDisplay amount={150000000} currency="USD" compact />
-
-<!-- Integer-backed masked input (prevents floating point errors) -->
-<MoneyInput bind:amount={price} currency="USD" />
-```
-
-## Persistence Drivers
-
-Rune Lab provides generic drivers to remember user preferences across reloads.
-Pass one to `config.persistence` on `<RuneProvider>`:
-
-- `cookieDriver`: Best for SSR applications (like SvelteKit) to prevent "theme
-  flash" on initial load.
-- `localStorageDriver`: Best for client-only applications (SPAs).
-- `sessionStorageDriver`: For preferences that should clear when the browser tab
-  closes.
-
-```svelte
-<script lang="ts">
-import { cookieDriver } from "rune-lab";
-</script>
-
-<RuneProvider config={{ persistence: cookieDriver }} plugins={[...]}>
-```
-
-## Advanced Patterns
+## Plugins
 
-### Store Observers (`onChange`)
-
-Beyond the `RuneProvider` props, you can imperatively subscribe to any
-`ConfigStore` (theme, language, currency) from your own services or components.
-Callbacks include `try/catch` protection so they never crash the store.
-
-```ts
-import { getThemeStore } from "rune-lab";
-
-const themeStore = getThemeStore();
-
-// Returns an unsubscribe function
-const unsub = themeStore.onChange((newId, oldId) => {
-  console.log(`Theme swapped from ${oldId} to ${newId}`);
-});
-```
-
-### Keyboard Shortcuts (Auto-Cleanup)
-
-Any component deep in your tree can register its own keyboard shortcuts using
-the `useShortcuts` composable. It handles Svelte's `$effect` lifecycle
-internally, ensuring shortcuts unregister when the component unmounts:
-
-```svelte
-<script lang="ts">
-import { getToastStore, useShortcuts } from "rune-lab";
+Rune Lab is modular. Plugins are documented in their respective directories:
 
-const toasts = getToastStore();
-
-useShortcuts([
-  {
-    id: "feature.save",
-    keys: "ctrl+s, cmd+s", // Comma-separated alternative keys
-    label: "Save Document",
-    category: "Editor",
-    scope: "global",
-    handler: (e) => {
-      e.preventDefault();
-      toasts.success("Document Saved!");
-    },
-  },
-]);
-</script>
-```
-
-### SvelteKit Route Syncing
-
-To keep your layout's active navigation state synchronized with the SvelteKit
-router, use an `$effect` inside your `+layout.svelte` right after the provider:
-
-```svelte
-<script lang="ts">
-import { page } from "$app/state";
-import { getLayoutStore } from "rune-lab";
-
-const layoutStore = getLayoutStore();
-
-$effect(() => {
-  // Automatically open the correct nav tree branch
-  const segment = page.url.pathname.split("/")[1] || "home";
-  layoutStore.navigate(segment);
-});
-</script>
-```
-
-### Calling Toasts from Outside Svelte Components
-
-If you need to trigger a toast from a pure `.ts` file (like a fetching utility
-or global error handler), you can use the Toast Bridge:
-
-```ts
-import { createToastBridge } from "rune-lab";
-
-const { notify } = createToastBridge();
-
-export async function fetchUser() {
-  try {
-    // ...
-  } catch (err) {
-    // Safely queues the toast if the UI hasn't mounted yet
-    notify("Failed to fetch user data", "error");
-  }
-}
-```
+- **Layout Plugin (`rune-lab/layout`)**:
+- **Palettes Plugin (`rune-lab/palettes`)**:
+- **i18n Plugin (`rune-lab/i18n`)**:
 
 ## License
 

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

@@ -1,7 +1,16 @@
+import type { Schema } from "effect";
 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 type SlotConfigInput<TSpec extends BaseSlotSpec> = TSpec extends {
+	config: Schema.Schema<infer TConfig, unknown, never>;
+}
+	? TConfig
+	: unknown;
+export type PluginConfigInput<TSlots extends Record<string, BaseSlotSpec>> = {
+	[K in keyof TSlots]?: SlotConfigInput<TSlots[K]>;
+};
 export interface ForgedPlugin<
 	TId extends string = string,
 	TSlots extends Record<string, BaseSlotSpec> = Record<string, BaseSlotSpec>,
@@ -13,6 +22,8 @@ export interface ForgedPlugin<
 	overlays?: unknown[];
 	contributions?: ContributionEntry<unknown>[];
 	descriptors: Record<keyof TSlots, SlotDescriptor>;
+	config?: Record<string, unknown>;
+	with(config: PluginConfigInput<TSlots>): ForgedPlugin<TId, TSlots>;
 }
 export type PluginInput =
 	| ForgedPlugin<string, Record<string, BaseSlotSpec>>

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

@@ -9,7 +9,7 @@ export function definePlugin(spec) {
 			accessorName: getAccessorName(slotName),
 		};
 	}
-	return {
+	const plugin = {
 		id: spec.id,
 		requires: spec.requires,
 		slots: slots,
@@ -17,5 +17,15 @@ export function definePlugin(spec) {
 		overlays: spec.overlays,
 		contributions: spec.contributions,
 		descriptors: descriptors,
+		with(config) {
+			return {
+				...this,
+				config: {
+					...(this.config || {}),
+					...config,
+				},
+			};
+		},
 	};
+	return plugin;
 }

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

@@ -13,6 +13,7 @@ export interface NormalizedSlot {
 	expose: boolean;
 	persist?: boolean | string[];
 	configSchema?: unknown;
+	pluginConfig?: Record<string, unknown>;
 	create: (context: SlotContext<unknown>) => unknown;
 }
 export declare function resolveSlotRef(

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

@@ -33,12 +33,6 @@ function normalizePlugins(inputs) {
 		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) => ({
@@ -97,6 +91,7 @@ export function normalizeSlots(sorted) {
 				expose: slotSpec.expose !== false,
 				persist: slotSpec.persist,
 				configSchema: slotSpec.config,
+				pluginConfig: plugin.config,
 				create: slotSpec.create,
 			};
 			allSlots.push(slot);
@@ -151,18 +146,22 @@ function buildLayers(slots, options) {
 		const storeLayer = Layer.effect(
 			storeTag,
 			Effect.gen(function* () {
-				const pluginConfig = getPluginConfig(slot.pluginId, options.config);
-				let configSlice = pluginConfig;
+				const rawConfig = slot.pluginConfig?.[slot.slotName];
+				let configSlice = rawConfig;
 				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}`,
-						);
+					if (rawConfig !== undefined) {
+						try {
+							configSlice = Schema.decodeUnknownSync(slot.configSchema)(
+								rawConfig,
+							);
+						} 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}`,
+							);
+						}
+					} else {
+						configSlice = undefined;
 					}
 				}
 				let persistenceHandle;

package/dist/src/plugins/layout/stores/layout.svelte.d.ts

@@ -1,11 +1,11 @@
 import type { SlotContext } from "rune-lab/core";
 import type { PresetState, WorkspaceItem } from "../types.js";
 export declare class LayoutStore {
+	#private;
 	workspaces: WorkspaceItem[];
 	activeWorkspaceId: string | null;
 	activeNavItemId: string | null;
 	collapsedSections: Set<string>;
-	preset: string;
 	zones: Record<
 		string,
 		{
@@ -14,6 +14,8 @@ export declare class LayoutStore {
 		}
 	>;
 	constructor(_ctx?: SlotContext<unknown>);
+	get preset(): string;
+	set preset(v: string);
 	applyPreset(presetId: string | PresetState): void;
 	toggleZone(zoneId: string): void;
 	setWorkspaces(items: WorkspaceItem[]): void;

package/dist/src/plugins/layout/stores/layout.svelte.js

@@ -5,7 +5,7 @@ export class LayoutStore {
 	activeNavItemId = $state(null);
 	collapsedSections = $state(new Set());
 	// Zone & Preset state
-	preset = $state("workspace");
+	#preset = $state("workspace");
 	zones = $state({
 		nav: { visible: true, size: 280 },
 		strip: { visible: true, size: 64 },
@@ -15,17 +15,23 @@ export class LayoutStore {
 		"overlay-anchor": { visible: true },
 	});
 	constructor(_ctx) {}
+	get preset() {
+		return this.#preset;
+	}
+	set preset(v) {
+		this.applyPreset(v);
+	}
 	applyPreset(presetId) {
 		if (typeof presetId === "string") {
 			const state = PRESETS[presetId];
 			if (state) {
-				this.preset = presetId;
+				this.#preset = presetId;
 				for (const [zone, val] of Object.entries(state)) {
 					this.zones[zone] = { ...val };
 				}
 			}
 		} else {
-			this.preset = "custom";
+			this.#preset = "custom";
 			for (const [zone, val] of Object.entries(presetId)) {
 				this.zones[zone] = { ...val };
 			}

package/dist/src/plugins/layout/stores/theme.svelte.js

@@ -51,13 +51,21 @@ export function createThemeStore(ctx) {
 		icon: "🎨",
 		driver: ctx.persistence,
 	});
-	if (!store.current && BROWSER) {
-		const prefersDark = globalThis.matchMedia(
-			"(prefers-color-scheme: dark)",
-		).matches;
-		const systemDefault = prefersDark ? "dark" : "light";
-		if (store.get(systemDefault)) {
-			store.set(systemDefault);
+	const saved = ctx.persistence.get("theme");
+	const hasPersisted =
+		typeof saved === "string" ? Boolean(saved && store.get(saved)) : false;
+	if (!hasPersisted) {
+		const configTheme = typeof ctx.config === "string" ? ctx.config : undefined;
+		if (configTheme && store.get(configTheme)) {
+			store.set(configTheme);
+		} else if (BROWSER) {
+			const prefersDark = globalThis.matchMedia(
+				"(prefers-color-scheme: dark)",
+			).matches;
+			const systemDefault = prefersDark ? "dark" : "light";
+			if (store.get(systemDefault)) {
+				store.set(systemDefault);
+			}
 		}
 	}
 	return store;