@sveltesentio/core 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0](https://github.com/golusoris/sveltesentio/compare/core-v0.2.1...core-v0.3.0) (2026-06-20)
+
+
+### Features
+
+* **core:** typed $sentio virtual-module config schema ([75e9f32](https://github.com/golusoris/sveltesentio/commit/75e9f32d378fe0d5457549cb793524317395a134))
+
 ## [0.2.1](https://github.com/golusoris/sveltesentio/compare/core-v0.2.0...core-v0.2.1) (2026-06-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltesentio/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Vite plugin, env schema, error types, id/clock utils — sveltesentio core",
   "type": "module",
   "private": false,
@@ -41,6 +41,9 @@
     "./eslint": {
       "import": "./src/eslint.ts",
       "types": "./src/eslint.ts"
+    },
+    "./sentio": {
+      "types": "./sentio.d.ts"
     }
   },
   "peerDependencies": {
@@ -79,6 +82,7 @@
   },
   "files": [
     "src",
+    "sentio.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {

package/sentio.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Ambient declaration for the `$sentio` virtual module emitted by
+ * `sentioPlugin` (see `@sveltesentio/core/vite`). Make it visible to your app
+ * by adding `"@sveltesentio/core/sentio"` to `compilerOptions.types`, or with
+ * `/// <reference types="@sveltesentio/core/sentio" />`.
+ *
+ * The exported shape matches `SentioConfig` from `defineSentioConfig`.
+ */
+declare module '$sentio' {
+	import type { SentioConfig, InterfaceType } from '@sveltesentio/core';
+
+	/** Build-time app version. */
+	export const version: string;
+	/** Default interface-type preset used before client-side classification. */
+	export const interfaceType: InterfaceType;
+	/** Static build-time feature flags (flag name → enabled). */
+	export const features: Readonly<Record<string, boolean>>;
+	/** Active theme preset name. */
+	export const theme: string;
+
+	const config: Readonly<SentioConfig>;
+	export default config;
+}

package/src/index.ts

@@ -47,4 +47,12 @@ export type {
 } from './vite.js';
 export { checkBundleBudget, sentioPlugin } from './vite.js';
 
+export type { InterfaceType, SentioConfig } from './sentio-config.js';
+export {
+	SentioConfigError,
+	defineSentioConfig,
+	interfaceTypeSchema,
+	sentioConfigSchema,
+} from './sentio-config.js';
+
 export { noDirectTime, sentioEslint } from './eslint.js';

package/src/sentio-config.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+
+/** Interface-type preset (§2.6): desktop pointer, 10-foot TV, handheld touch. */
+export const interfaceTypeSchema = z.enum(['desktop', 'tenfoot', 'handheld']);
+export type InterfaceType = z.infer<typeof interfaceTypeSchema>;
+
+/**
+ * Schema for the typed `$sentio` virtual module — build-time configuration
+ * surfaced to client + server code via `import { ... } from '$sentio'`. Feed
+ * the validated result of {@link defineSentioConfig} to the Vite plugin as
+ * `sentioPlugin({ virtualModule })`.
+ */
+export const sentioConfigSchema = z.object({
+	/** Build-time app version surfaced to client code. */
+	version: z.string().min(1).default('0.0.0'),
+	/** Default interface-type preset used before client-side classification. */
+	interfaceType: interfaceTypeSchema.default('desktop'),
+	/** Static feature flags resolved at build time (flag name → enabled). */
+	features: z.record(z.string(), z.boolean()).default({}),
+	/** Active theme preset name. */
+	theme: z.string().min(1).default('default'),
+});
+
+export type SentioConfig = z.infer<typeof sentioConfigSchema>;
+
+/** Thrown by {@link defineSentioConfig} when the input fails validation. */
+export class SentioConfigError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'SentioConfigError';
+	}
+}
+
+/**
+ * Validate + normalise a `$sentio` config. Fills defaults for omitted fields
+ * and throws {@link SentioConfigError} with a readable summary on invalid
+ * input, so misconfiguration fails the build instead of reaching the client.
+ */
+export function defineSentioConfig(input: unknown = {}): SentioConfig {
+	const result = sentioConfigSchema.safeParse(input);
+	if (!result.success) {
+		const detail = result.error.issues
+			.map((issue) => `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+			.join('\n');
+		throw new SentioConfigError(`[sentio] Invalid $sentio config:\n${detail}`);
+	}
+	return result.data;
+}