@sveltesentio/core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Bug Fixes
+
+* **core:** restore eslint.config.ts + chart-a11y rule (prior commit's git add aborted) ([a978cf6](https://github.com/golusoris/sveltesentio/commit/a978cf6f4a362b1fb83eabdc426e6b04276607c3))
+
 ## [0.2.0](https://github.com/golusoris/sveltesentio/compare/core-v0.1.0...core-v0.2.0) (2026-06-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltesentio/core",
-  "version": "0.2.0",
+  "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": {
@@ -58,15 +61,16 @@
     }
   },
   "devDependencies": {
-    "@sveltejs/kit": "^2.65.1",
+    "@sveltejs/kit": "^2.65.2",
     "@types/node": "^24.13.2",
     "esm-env": "^1.2.2",
     "openapi-fetch": "^0.17.0",
     "svelte": "^5.56.3",
     "typescript": "^6.0.3",
     "uuid": "^14.0.0",
-    "vitest": "^4.1.8",
-    "zod": "^4.4.3"
+    "vitest": "^4.1.9",
+    "zod": "^4.4.3",
+    "svelte-eslint-parser": "^1.8.0"
   },
   "keywords": [
     "sveltesentio",
@@ -78,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/eslint.ts

@@ -1,14 +1,18 @@
 import type { Rule } from 'eslint';
 
 /**
- * Flat-config ESLint plugin enforcing the core "no direct time reads" invariant
- * (see AGENTS.md §Invariants + docs/principles.md §2.1): time must flow through
- * the injected {@link Clock} (`useClock` / `getClock` from `@sveltesentio/core`)
- * so it is deterministic and testable. Banned forms:
+ * Flat-config ESLint plugin bundling sveltesentio's two cross-package
+ * invariants:
  *
- * - `Date.now()`
- * - `new Date()` (zero-argument — `new Date(serverMs)` is explicit + allowed)
- * - `performance.now()`
+ * - `no-direct-time` — time must flow through the injected {@link Clock}
+ *   (`useClock` / `getClock` from `@sveltesentio/core`) so it is deterministic
+ *   and testable (AGENTS.md §Invariants + docs/principles.md §2.1). Banned forms:
+ *   `Date.now()`, zero-argument `new Date()`, `performance.now()`.
+ * - `chart-a11y-wrapper` — every chart visual rendered from `layerchart` /
+ *   `uplot` must go through `@sveltesentio/charts`' `<ChartFigure>` so the WCAG
+ *   2.2 SC 1.1.1 text alternative cannot be skipped (charts/AGENTS.md §Invariants,
+ *   ADR-0013). A bare `<LineChart>` / `<Chart>` / uPlot element with no
+ *   `<ChartFigure>` ancestor is an error.
  *
  * Register in a flat `eslint.config.js`:
  *
@@ -20,6 +24,11 @@ import type { Rule } from 'eslint';
  *     plugins: { '@sveltesentio': sentio },
  *     rules: { '@sveltesentio/no-direct-time': 'error' },
  *   },
+ *   {
+ *     files: ['src/**\/*.svelte'],
+ *     plugins: { '@sveltesentio': sentio },
+ *     rules: { '@sveltesentio/chart-a11y-wrapper': 'error' },
+ *   },
  * ];
  * ```
  */
@@ -29,6 +38,7 @@ import type { Rule } from 'eslint';
 type Node = Rule.Node;
 type CallExpressionNode = Extract<Node, { type: 'CallExpression' }>;
 type NewExpressionNode = Extract<Node, { type: 'NewExpression' }>;
+type ImportDeclarationNode = Extract<Node, { type: 'ImportDeclaration' }>;
 type Callee = CallExpressionNode['callee'];
 
 const CLOCK_HINT =
@@ -92,16 +102,108 @@ const noDirectTime: Rule.RuleModule = {
 	},
 };
 
+// --- chart-a11y-wrapper ------------------------------------------------------
+
+const CHART_LIBS = ['layerchart', 'uplot'] as const;
+
+/** The a11y wrappers from `@sveltesentio/charts` that satisfy the invariant. */
+const A11Y_WRAPPER_ELEMENTS = new Set(['ChartFigure']);
+
+const CHART_HINT =
+	'render it inside `<ChartFigure>` from @sveltesentio/charts so the chart ' +
+	'ships the required visually-hidden data table (WCAG 2.2 SC 1.1.1, ADR-0013)';
+
+/**
+ * Structural read of a `svelte-eslint-parser` `SvelteElement` name without
+ * depending on the parser's types: a component element exposes
+ * `name: { type: 'Identifier' | 'SvelteName', name: string }`. Anything else
+ * (HTML tags, member-expression names) is not a chart-library binding and is
+ * intentionally ignored.
+ */
+function svelteElementName(node: unknown): string | undefined {
+	if (typeof node !== 'object' || node === null) return undefined;
+	const name = (node as { name?: unknown }).name;
+	if (typeof name !== 'object' || name === null) return undefined;
+	const raw = (name as { name?: unknown }).name;
+	return typeof raw === 'string' ? raw : undefined;
+}
+
+/** Reads the source string of a (validated) `ImportDeclaration`. */
+function importSource(node: ImportDeclarationNode): string {
+	const value = node.source.value;
+	return typeof value === 'string' ? value : '';
+}
+
+/** True for `layerchart`, `layerchart/...`, `uplot`, `uplot/...`. */
+function isChartLibSource(source: string): boolean {
+	return CHART_LIBS.some(
+		(lib) => source === lib || source.startsWith(`${lib}/`),
+	);
+}
+
+const chartA11yWrapper: Rule.RuleModule = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'require chart visuals from layerchart / uplot to be wrapped in <ChartFigure>',
+			recommended: true,
+		},
+		schema: [],
+		messages: {
+			bareChart: `Bare \`<{{name}}>\` from \`{{source}}\` bypasses the a11y wrapper — ${CHART_HINT}.`,
+		},
+	},
+
+	create(context: Rule.RuleContext): Rule.RuleListener {
+		// Local binding names imported from a chart library → the source they
+		// came from, so the message can name it.
+		const chartBindings = new Map<string, string>();
+
+		return {
+			ImportDeclaration(node: ImportDeclarationNode): void {
+				const source = importSource(node);
+				if (!isChartLibSource(source)) return;
+				for (const spec of node.specifiers) {
+					chartBindings.set(spec.local.name, source);
+				}
+			},
+
+			// `SvelteElement` is the svelte-eslint-parser node for any element;
+			// not part of ESLint's core `NodeListener`, so it rides the
+			// RuleListener index signature.
+			SvelteElement(node: Rule.Node): void {
+				const name = svelteElementName(node);
+				if (name === undefined) return;
+				const source = chartBindings.get(name);
+				if (source === undefined) return;
+				// Allowed when nested under a sanctioned a11y wrapper element.
+				const ancestors = context.sourceCode.getAncestors(node);
+				const wrapped = ancestors.some((ancestor) =>
+					A11Y_WRAPPER_ELEMENTS.has(svelteElementName(ancestor) ?? ''),
+				);
+				if (wrapped) return;
+				context.report({
+					node,
+					messageId: 'bareChart',
+					data: { name, source },
+				});
+			},
+		};
+	},
+};
+
 /** The flat-config plugin object (`plugins: { '@sveltesentio': sentioEslint }`). */
 const sentioEslint = {
-	meta: { name: '@sveltesentio/core', version: '0.1.0' },
+	meta: { name: '@sveltesentio/core', version: '0.2.0' },
 	rules: {
 		'no-direct-time': noDirectTime,
+		'chart-a11y-wrapper': chartA11yWrapper,
 	},
 } satisfies {
 	meta: { name: string; version: string };
 	rules: Record<string, Rule.RuleModule>;
 };
 
-export { noDirectTime, sentioEslint };
+export { noDirectTime, chartA11yWrapper, sentioEslint };
 export default sentioEslint;

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;
+}