@hkdigital/lib-core 0.4.28 → 0.4.30

package/CLAUDE.md

@@ -0,0 +1,350 @@
+# SvelteKit Library
+
+## Project Overview
+This is a modern SvelteKit library built with Svelte 5 and Skeleton.dev v3 components. The project emphasizes accessibility, clean code standards, and modern JavaScript patterns.
+
+## Architecture & Structure
+- **Framework**: SvelteKit with Svelte 5 runes
+- **UI Components**: Skeleton.dev version 3
+- **Package Manager**: PNPM
+- **Language**: Modern JavaScript (ES6+), no TypeScript
+- **Module System**: ES Modules only (import/export)
+
+## Key Technical Decisions
+- Uses Svelte 5 runes (`$state()`, `$derived()`, `$effect()`, `$props()`) for state management
+- Snippet syntax with `{@render children()}` instead of deprecated `<slot />`
+- WCAG 2.1 Level AA accessibility compliance
+- 80-character line limit with rare exceptions
+- Two-space indentation
+- Descriptive camelCase naming conventions
+
+## Component Patterns
+- All components use `let { ... } = $props()` with JSDoc type annotations
+- Props always include `classes` and `...attrs` for flexibility
+- Event handlers use Svelte 5 syntax (`onclick`, `onchange`)
+- Snippet props typed as `import('svelte').Snippet`
+- Private methods use hash prefix (`#methodName`)
+
+## JavaScript Class Patterns
+- Use modern ES private methods with hash prefix: `#methodName()` instead of `_methodName()`
+- Private fields also use hash prefix: `#privateField`
+- Apply this to all JavaScript classes, not just Svelte components
+- Never use `@private` in JSDoc for methods that start with `#` - the hash already indicates privacy
+
+## Development Standards
+- Readable code over concise code
+- Explicit error handling with try/catch for async operations
+- JSDoc comments for all functions and variables
+- English for all documentation and comments
+- No dollar signs in variable names (reserved for Svelte)
+
+### ESLint Rule Suppression
+- Use specific rule suppression instead of blanket disables
+- For unused variables in method signatures (e.g., base class methods to be overridden):
+  ```javascript
+  // eslint-disable-next-line no-unused-vars
+  async _configure(newConfig, oldConfig = null) {
+    // Override in subclass
+  }
+  ```
+
+## Documentation & Comment Style
+- **80-character line limit** - strictly enforce for ALL code and documentation
+  - Applies to code lines, JSDoc comments, parameter descriptions, and all text
+  - Wrap long JSDoc descriptions across multiple lines
+  - Break long parameter lists and descriptions at 80 characters
+- **JSDoc formatting conventions:**
+  - Blank line between description and first `@param`
+  - Blank line between last `@param` and `@returns`
+  - No blank lines between consecutive `@param` tags with short descriptions
+  - Add extra newlines between `@param` entries ONLY when they have multi-line descriptions for better readability
+  - For long parameter types or descriptions, place description on next line:
+    ```javascript
+    // Multi-line @param descriptions (use extra newlines between)
+    /**
+     * Convert a path string to an array path
+     *
+     * @param {string|string[]} path
+     *   String or array path (e.g. "some.path.to")
+     *
+     * @param {string} [pathSeparator=PATH_SEPARATOR]
+     *   A custom path separator to use instead of the default "."
+     *
+     * @returns {string[]} array path (e.g. ["some", "path", "to"])
+     */
+
+    // Short descriptions (no extra newlines needed)
+    /**
+     * Log an info message
+     *
+     * @param {string} message - Log message
+     * @param {*} [details] - Additional details
+     *
+     * @returns {boolean} True if the log was emitted
+     */
+    ```
+- **Concise descriptions** - avoid obvious/redundant explanations
+- Keep only essential information that adds value for developers
+- Remove descriptions that simply restate parameter names or types
+- Examples:
+  - ✅ `@property {number} [exp] - Expiration time (seconds since epoch)`
+  - ❌ `@property {number} [exp] - Expiration time - timestamp when the JWT expires`
+  - ✅ `@property {boolean} [ignoreExpiration] - Skip expiration validation`  
+  - ❌ `@property {boolean} [ignoreExpiration] - If true, do not validate the expiration of the token`
+
+## Writing Style
+- Use normal English capitalization rules - avoid unnecessary capitals
+- Don't capitalize common nouns like "server", "client", "button", "error", "validation", etc.
+- Only capitalize proper nouns, beginnings of sentences, and official names
+- Examples:
+  - ✅ "server-side validation" not "Server-side Validation"  
+  - ✅ "expect function" not "Expect Function"
+  - ✅ "client error" not "Client Error"
+  - ✅ "JavaScript" (proper noun) but "validation error" (common noun)
+
+## Import Path Conventions
+- Use `$lib/domain/...` imports for cross-domain references (e.g., `$lib/media/image.js`, `$lib/network/http.js`)
+- Use relative imports (`./` or `../`) when staying within the same main folder under `$lib`
+- **Always include file extensions** (`.js`, `.svelte`) in import statements
+- **For cross-domain imports, use specific export files** (e.g., `parsers.js`, `valibot.js`) rather than directory-only paths - this ensures compatibility outside the library
+- **For local imports within the same domain**, import specific files directly (e.g., `./ClassName.js`) rather than using local index files
+- Examples:
+  - ✅ `import { ImageLoader } from '$lib/media/image.js'` (cross-domain import)
+  - ✅ `import ImageLoader from './ImageLoader.svelte.js'` (local import within same domain)
+  - ✅ `import IterableTree from './IterableTree.js'` (local import within same domain)
+  - ✅ `import { v } from '$lib/valibot/valibot.js'` (cross-domain with specific export file)
+  - ✅ `import { HumanUrl, Email } from '$lib/valibot/parsers.js'` (cross-domain with specific export file)
+  - ❌ `import { v, HumanUrl } from '$lib/valibot'` (missing specific export file)
+  - ❌ `import { IterableTree } from './index.js'` (local index when specific file should be used)
+  - ❌ `import something from '../../media/image.js'` (cross-domain relative import)
+
+## Class Export Conventions
+- **All classes should be default exports**: `export default class ClassName`
+- **Import classes without destructuring**: `import ClassName from './ClassName.js'`
+- Examples:
+  - ✅ `export default class HkPromise extends Promise {}`
+  - ✅ `import HkPromise from './HkPromise.js'`
+  - ❌ `export class HkPromise extends Promise {}` (named export)
+  - ❌ `import { HkPromise } from './HkPromise.js'` (destructuring import)
+
+## Accessibility Requirements
+- Proper ARIA roles, states, and properties
+- Descriptive aria-labels for interactive elements
+- Keyboard navigation support
+- Logical tab order and focus management
+- Proper heading hierarchy
+- Screen reader compatibility (VoiceOver, NVDA)
+
+## Common Patterns to Follow
+- Server/client code separation in SvelteKit
+- Clear component hierarchy
+- Minimal, targeted changes to working code
+- Ask before making assumptions about existing structure
+- Focus on specific requests rather than general improvements
+
+## Design System Usage in Examples
+
+When creating examples in `routes/examples/`, always use the HKdigital Design System:
+
+### Typography
+- Use complete typography classes: `type-heading-h1`, `type-base-md`, `type-ui-sm`
+- Include dark mode variants when relevant: `type-heading-h1-dark`
+- Never use raw Tailwind text classes like `text-lg` - use `text-base-lg` instead
+
+### Spacing
+- Use UI points for element spacing: `p-20up`, `m-10up`, `gap-16up`
+- Use text-based spacing for typography-related spacing: `mb-16bt`, `mt-12ut`
+- Never use raw Tailwind spacing like `p-4` - use `p-4up` instead
+
+### Colors
+- Use themed colors: `bg-primary-500`, `bg-surface-100`, `text-error-500`
+- Always use contrast colors for accessibility: `text-primary-contrast-500`
+- Include both light and dark mode considerations
+
+### Layout & Components
+- Use design system utilities: `rounded-md`, `border-width-normal`
+- Follow the responsive scaling system built around 1024×768 design reference
+- Use component data attributes: `data-component="button"` `data-role="primary"`
+
+### Custom Styling for Examples
+When examples require custom CSS beyond the design system:
+
+- Always add a `data-page` attribute to the outer page element
+- Create a `style.css` file alongside the `+page.svelte` file
+- Use `<style src="./style.css"></style>` to include the styles
+- Scope all CSS rules under `[data-page]` to prevent global conflicts
+- Use CSS nesting syntax for better organization
+
+**Example structure:**
+```svelte
+<!-- +page.svelte -->
+<div data-page>
+  <div data-section="content">
+    <!-- example content -->
+  </div>
+</div>
+
+<style src="./style.css"></style>
+```
+
+```css
+/* style.css */
+[data-page] {
+  & [data-section="content"] {
+    /* scoped styles here */
+    position: relative;
+    padding: 20px;
+  }
+  
+  & .custom-element {
+    /* more scoped styles */
+  }
+}
+```
+
+### Structure
+- Always include proper heading hierarchy (`type-heading-h1`, `type-heading-h2`, etc.)
+- Use semantic HTML with appropriate ARIA attributes
+- Follow WCAG 2.1 Level AA accessibility guidelines
+
+### UI Components
+- Always use components from `$lib/ui/primitives/` when available
+- Prefer the `Button` component over raw `<button>` elements
+- Import from the index: `import { Button } from '$lib/ui/primitives.js'`
+- Use snippet syntax: `<Button>{content}</Button>` instead of slot syntax
+
+### Example Template
+```svelte
+<script>
+  import { Button } from '$lib/ui/primitives.js';
+</script>
+
+<div class="container mx-auto p-20up" data-page>
+  <h1 class="type-heading-h1 mb-20up">Example Title</h1>
+  
+  <div class="card p-20up mb-20up">
+    <p class="type-base-md mb-12bt">Description text</p>
+    <Button>
+      Action
+    </Button>
+  </div>
+</div>
+
+<!-- Only include if custom CSS is needed -->
+<style src="./style.css"></style>
+```
+
+## Styling System & Tailwind CSS
+
+### Critical: Design System Spacing Values
+
+**IMPORTANT**: Only use spacing values that exist in the design system configuration. Invalid spacing utilities will cause build failures.
+
+#### Available Viewport-Based Spacing (`up` suffix)
+Valid values: `1up`, `2up`, `4up`, `5up`, `6up`, `10up`, `20up`, `30up`, `40up`, `50up`, `60up`, `70up`, `80up`, `90up`, `100up`, `120up`, `140up`, `160up`, `180up`, `200up`
+
+#### Available Text-Based Spacing (`ut`, `bt`, `ht` suffixes)  
+Valid values: `1ut/bt/ht`, `2ut/bt/ht`, `4ut/bt/ht`, `6ut/bt/ht`, `8ut/bt/ht`, `10ut/bt/ht`, `11ut/bt/ht`, `12ut/bt/ht`, `16ut/bt/ht`, `20ut/bt/ht`, `24ut/bt/ht`, `28ut/bt/ht`, `32ut/bt/ht`, `36ut/bt/ht`, `50ut/bt/ht`
+
+#### ❌ Common Invalid Values (Will Cause Build Failures)
+- `p-16up` (use `p-20up` instead)
+- `px-16up py-12up` (use `px-20up py-10up` instead)
+- `mb-16up` (use `mb-20up` instead)
+- Any spacing value not listed above
+
+### External CSS Files (`<style src="./style.css">`)
+
+When using external CSS files with `@apply` directives, you **MUST** include the `@reference` directive:
+
+#### ✅ Correct External CSS
+```css
+/* style.css */
+@reference '../../app.css';
+
+[data-page] {
+  & .my-component {
+    @apply p-20up bg-surface-300 border border-primary-500;
+  }
+}
+```
+
+#### ❌ Broken External CSS
+```css
+/* style.css - MISSING @reference */
+[data-page] {
+  & .my-component {
+    @apply p-20up bg-surface-300; /* ERROR: Cannot apply unknown utility class */
+  }
+}
+```
+
+### Path Resolution for @reference
+
+The `@reference` path must be relative to your CSS file's location:
+- From `/src/routes/examples/style.css` → `@reference '../../app.css'`
+- From `/src/routes/examples/ui/style.css` → `@reference '../../../app.css'`
+- From `/src/lib/components/style.css` → `@reference '../../app.css'`
+
+### Inline vs External CSS
+
+#### Inline Styles (No @reference needed)
+```svelte
+<style>
+  [data-page] {
+    & .my-component {
+      @apply p-20up bg-surface-300 border border-primary-500;
+    }
+  }
+</style>
+```
+
+#### External CSS (Requires @reference)
+```svelte
+<!-- Component.svelte -->
+<div class="my-component">Content</div>
+<style src="./style.css"></style>
+```
+
+### Troubleshooting Build Errors
+
+#### "Cannot apply unknown utility class 'p-XYZup'"
+1. Check if the spacing value exists in `VIEWPORT_POINT_SIZES` or `TEXT_POINT_SIZES`
+2. Replace with the nearest valid value (e.g., `16up` → `20up`)
+3. If using external CSS, verify `@reference` directive is present and path is correct
+
+#### "Are you using CSS modules or similar and missing @reference?"
+1. Add `@reference '../../app.css'` at the top of your external CSS file
+2. Verify the relative path from CSS file to `src/app.css` is correct
+3. Consider switching to inline styles if path resolution is problematic
+
+### Design System Integration
+
+#### Always Use Design System Classes
+- ✅ `type-heading-h1`, `type-base-md`, `type-ui-sm`
+- ✅ `p-20up`, `m-10up`, `gap-16up` (viewport-based)
+- ✅ `mb-16bt`, `mt-12ut` (text-based)
+- ✅ `bg-surface-300`, `text-primary-500`, `border-error-500`
+- ❌ Raw Tailwind: `text-lg`, `p-4`, `bg-gray-300`
+
+#### Color System
+All design system colors are available with contrast variants:
+- Base colors: `bg-primary-500`, `bg-surface-100`, `bg-error-500`
+- Contrast colors: `text-primary-contrast-500`, `text-surface-contrast-100`
+- Shades: `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `950`
+
+### CSS Architecture
+- Use `[data-page]` scoping for page-specific styles
+- Use `[data-component]` attributes for component identification  
+- Prefer CSS nesting with `&` selector
+- Layer styles: `@layer theme, base, utilities, components`
+
+## What Not to Do
+- Don't use deprecated Svelte 4 syntax
+- Don't mix slot and snippet syntax
+- Don't use TypeScript syntax
+- Don't use CommonJS (require/module.exports)
+- Don't use underscore prefixes for private methods
+- Don't use invalid spacing values (e.g., `p-16up`, `mb-14up`) - check design system configuration
+- Don't use external CSS with `@apply` without the `@reference` directive
+- Don't modify unrelated code unless necessary
+- **NEVER run `npm run dev` or `pnpm run dev`** - it interferes with the user's running development server

package/README.md

@@ -187,10 +187,16 @@ The library includes a comprehensive logging system that provides:
 - **Client-side**: Enhanced console logging with structured data display in browser inspector
 - **Consistent API**: Same logging interface for both server and client environments
 
-For detailed setup guides see:
-- **Design system**: [src/lib/design/README.md](./src/lib/design/README.md)
-- **Vite configuration**: [src/lib/config/README.md](./src/lib/config/README.md)
-- **Logging system**: [src/lib/logging/README.md](./src/lib/logging/README.md)
+## Documentation
+
+For detailed setup guides and configuration:
+- **Project setup**: [docs/setup/new-project.md](./docs/setup/new-project.md) - SvelteKit project setup
+- **Library setup**: [docs/setup/new-lib.md](./docs/setup/new-lib.md) - SvelteKit library setup
+- **Services & logging**: [docs/setup/services-logging.md](./docs/setup/services-logging.md) - Service management architecture
+- **Configuration files**: [docs/config/root-config-files.md](./docs/config/root-config-files.md) - Config file reference
+- **Design system**: [src/lib/design/README.md](./src/lib/design/README.md) - Design tokens and theming
+- **Vite configuration**: [src/lib/config/README.md](./src/lib/config/README.md) - Build configuration
+- **Logging system**: [src/lib/logging/README.md](./src/lib/logging/README.md) - Server and client logging
 
 ### Update
 

package/dist/logging/index.d.ts

@@ -1,5 +1,5 @@
 export { createServerLogger } from "./internal/factories/server.js";
 export { createClientLogger } from "./internal/factories/client.js";
 export { Logger } from "./internal/logger/index.js";
-export * from "./constants.js";
+export * from "./levels.js";
 export * from "./typedef.js";

package/dist/logging/index.js

@@ -5,6 +5,6 @@ export { createClientLogger } from './internal/factories/client.js';
 // Logger (for advanced usage)
 export { Logger } from './internal/logger/index.js';
 
-// Constants and typedefs
-export * from './constants.js';
+export * from './levels.js';
+
 export * from './typedef.js';

package/dist/logging/internal/adapters/console.js

@@ -1,5 +1,5 @@
 import { dev } from '$app/environment';
-import { LEVELS } from '../../constants.js';
+import { LEVELS } from '../../levels.js';
 import {
   findRelevantFrameIndex,
   detectErrorMeta,

package/dist/logging/internal/factories/client.js

@@ -1,6 +1,6 @@
 import { Logger } from '../logger/index.js';
 import { ConsoleAdapter } from '../adapters/console.js';
-import { INFO } from '../../constants.js';
+import { INFO } from '../../levels.js';
 
 /**
  * Create a client-side logger with console adapter

package/dist/logging/internal/factories/server.js

@@ -1,6 +1,6 @@
 import { Logger } from '../logger/index.js';
 import { PinoAdapter } from '../adapters/pino.js';
-import { INFO } from '../../constants.js';
+import { INFO } from '../../levels.js';
 // import { expectNoSSRContext } from '../../../util/ssr/index.js';
 
 /**

package/dist/logging/internal/logger/Logger.js

@@ -43,7 +43,7 @@ import {
   ERROR,
   LEVELS,
   LOG
-} from '../../constants.js';
+} from '../../levels.js';
 
 import { DetailedError } from '../../../generic/errors.js';
 // import { LoggerError } from '../../errors.js';

package/dist/services/README.md

@@ -237,6 +237,37 @@ const systemHealth = await manager.checkHealth();
 
 ### Error Handling and Recovery
 
+### Logging Configuration
+
+ServiceManager provides centralized logging control for all services:
+
+```javascript
+const manager = new ServiceManager({
+  debug: true,                    // Sets defaultLogLevel to DEBUG
+  defaultLogLevel: 'INFO',        // Default level for all services
+  managerLogLevel: 'DEBUG',       // Level for ServiceManager itself
+  serviceLogLevels: {             // Per-service levels
+    database: 'ERROR',
+    auth: 'DEBUG'
+  }
+});
+
+// Change manager log level at runtime
+manager.setManagerLogLevel('ERROR');
+
+// Change service log levels at runtime
+manager.setServiceLogLevel('database', 'INFO');
+
+// Set multiple service levels at once
+manager.setServiceLogLevel({
+  database: 'INFO',
+  auth: 'DEBUG'
+});
+
+// Parse string format
+manager.setServiceLogLevel('database:info,auth:debug');
+```
+
 ### ServiceManager events
 
 ServiceManager emits these events (constants from `$lib/services/service-manager/constants.js`):
@@ -264,14 +295,14 @@ await manager.recoverService('database');
 Forward all service log events to a centralised logger:
 
 ```javascript
-import { ServiceManager, SERVICE_LOG } from '$lib/services/index.js';
+import { ServiceManager } from '$lib/services/index.js';
 import { createServerLogger } from '$lib/logging/index.js';
 
 const manager = new ServiceManager();
 const logger = createServerLogger('SystemLogger');
 
 // Listen to all log events and forward them to the logger
-manager.on(SERVICE_LOG, (logEvent) => {
+const unsubscribe = manager.onServiceLogEvent((logEvent) => {
   logger.logFromEvent('manager:service:log', logEvent);
 });
 
@@ -280,6 +311,9 @@ manager.register('database', DatabaseService, { ... });
 manager.register('auth', AuthService, { ... });
 
 await manager.startAll();
+
+// Cleanup when done
+unsubscribe();
 ```
 
 ## Plugins

package/dist/services/service-manager/ServiceManager.d.ts

@@ -129,12 +129,32 @@ export class ServiceManager extends EventEmitter {
      */
     isRunning(name: string): Promise<boolean>;
     /**
-     * Set log level for a service or globally
+     * Listen to log messages emitted by individual services
      *
-     * @param {string} name - Service name or '*' for global
-     * @param {string} level - Log level to set
+     * @param {Function} listener - Log event handler
+     *
+     * @returns {Function} Unsubscribe function
+     */
+    onServiceLogEvent(listener: Function): Function;
+    /**
+     * Set log level for the ServiceManager itself
+     *
+     * @param {string} level - Log level to set for the ServiceManager
+     */
+    setManagerLogLevel(level: string): void;
+    /**
+     * Set log level for individual services
+     *
+     * @param {string|Object<string,string>} nameOrConfig
+     *   Service configuration:
+     *   - String with service name: 'auth' (requires level parameter)
+     *   - String with config: 'auth:debug,database:info'
+     *   - Object: { auth: 'debug', database: 'info' }
+     * @param {string} [level] - Log level (required when nameOrConfig is service name)
      */
-    setLogLevel(name: string, level: string): void;
+    setServiceLogLevel(nameOrConfig: string | {
+        [x: string]: string;
+    }, level?: string): void;
     /**
      * Get all services with a specific tag
      *

package/dist/services/service-manager/ServiceManager.js

@@ -51,11 +51,11 @@
  *
  * @example
  * // Logging control
- * // Set global log level
- * manager.setLogLevel('*', 'DEBUG');
+ * // Set manager log level (affects all services)
+ * manager.setManagerLogLevel('DEBUG');
  *
  * // Set specific service log level
- * manager.setLogLevel('database', 'ERROR');
+ * manager.setServiceLogLevel('database', 'ERROR');
  *
  * // Listen to all service logs
  * manager.on('service:log', (logEvent) => {
@@ -64,7 +64,10 @@
  */
 
 import { EventEmitter } from '../../generic/events.js';
-import { Logger, DEBUG, INFO, WARN } from '../../logging/index.js';
+import { Logger, DEBUG, INFO } from '../../logging/index.js';
+
+import { SERVICE_LOG } from './constants.js';
+import { parseServiceLogLevels } from './util.js';
 
 import {
   STATE_NOT_CREATED,
@@ -103,18 +106,29 @@ export class ServiceManager extends EventEmitter {
     /** @type {Map<string, ServiceEntry>} */
     this.services = new Map();
 
+    const defaultLogLevel =
+      config.defaultLogLevel || (config.debug ? DEBUG : INFO);
+    const managerLogLevel = config.managerLogLevel || defaultLogLevel;
+    const serviceLogLevels = config.serviceLogLevels;
+
     /** @type {Logger} */
-    this.logger = new Logger('ServiceManager', config.logLevel || INFO);
+    this.logger = new Logger('ServiceManager', managerLogLevel);
 
     /** @type {ServiceManagerConfig} */
     this.config = {
       debug: config.debug ?? false,
       autoStart: config.autoStart ?? false,
       stopTimeout: config.stopTimeout || 10000,
-      logConfig: config.logConfig || {}
+      defaultLogLevel
+      // managerLogLevel will be set bysetManagerLogLevel()
+      // serviceLogLevels will be set by setServiceLogLevel()
     };
 
-    this.#setupLogging();
+    this.setManagerLogLevel(managerLogLevel);
+
+    if (serviceLogLevels) {
+      this.setServiceLogLevel(serviceLogLevels);
+    }
   }
 
   /**
@@ -474,34 +488,70 @@ export class ServiceManager extends EventEmitter {
   }
 
   /**
-   * Set log level for a service or globally
+   * Listen to log messages emitted by individual services
    *
-   * @param {string} name - Service name or '*' for global
-   * @param {string} level - Log level to set
+   * @param {Function} listener - Log event handler
+   *
+   * @returns {Function} Unsubscribe function
    */
-  setLogLevel(name, level) {
-    if (name === '*') {
-      // Global level
-      this.config.logConfig.globalLevel = level;
-
-      // Apply to all existing services
-      // eslint-disable-next-line no-unused-vars
-      for (const [_, entry] of this.services) {
-        if (entry.instance) {
-          entry.instance.setLogLevel(level);
+  onServiceLogEvent(listener) {
+    return this.on(SERVICE_LOG, listener);
+  }
+
+  /**
+   * Set log level for the ServiceManager itself
+   *
+   * @param {string} level - Log level to set for the ServiceManager
+   */
+  setManagerLogLevel(level) {
+    this.config.managerLogLevel = level;
+    this.logger.setLevel(level);
+  }
+
+  /**
+   * Set log level for individual services
+   *
+   * @param {string|Object<string,string>} nameOrConfig
+   *   Service configuration:
+   *   - String with service name: 'auth' (requires level parameter)
+   *   - String with config: 'auth:debug,database:info'
+   *   - Object: { auth: 'debug', database: 'info' }
+   * @param {string} [level] - Log level (required when nameOrConfig is service name)
+   */
+  setServiceLogLevel(nameOrConfig, level) {
+    /** @type {{[name:string]: string}} */
+    let serviceLevels = {};
+
+    if (typeof nameOrConfig === 'string') {
+      if (nameOrConfig.includes(':')) {
+        // Parse string config: 'auth:debug,database:info'
+        serviceLevels = parseServiceLogLevels(nameOrConfig);
+      } else {
+        // Single service name
+        if (!level) {
+          throw new Error(
+            `Level parameter required for service '${nameOrConfig}'`
+          );
         }
+        serviceLevels[nameOrConfig] = level;
       }
     } else {
-      // Service-specific level
-      if (!this.config.logConfig.serviceLevels) {
-        this.config.logConfig.serviceLevels = {};
-      }
-      this.config.logConfig.serviceLevels[name] = level;
+      // Object config: { auth: 'debug', database: 'info' }
+      serviceLevels = nameOrConfig;
+    }
+
+    if (!this.config.serviceLogLevels) {
+      this.config.serviceLogLevels = {};
+    }
+
+    // Apply service-specific log levels
+    for (const [name, logLevel] of Object.entries(serviceLevels)) {
+      this.config.serviceLogLevels[name] = logLevel;
 
       // Apply to existing instance
       const instance = this.get(name);
       if (instance) {
-        instance.setLogLevel(level);
+        instance.setLogLevel(logLevel);
       }
     }
   }
@@ -586,23 +636,6 @@ export class ServiceManager extends EventEmitter {
     }
   }
 
-  /**
-   * Setup logging configuration based on config.dev
-   */
-  #setupLogging() {
-    // Set default log levels based on config.debug flag
-    if (this.config.debug) {
-      this.config.logConfig.defaultLevel = DEBUG;
-    } else {
-      this.config.logConfig.defaultLevel = WARN;
-    }
-
-    // Apply config
-    if (this.config.logConfig.globalLevel) {
-      this.logger.setLevel(this.config.logConfig.globalLevel);
-    }
-  }
-
   /**
    * Get the appropriate log level for a service
    *
@@ -611,21 +644,20 @@ export class ServiceManager extends EventEmitter {
    * @returns {string|undefined} Log level or undefined
    */
   #getServiceLogLevel(name) {
-    const config = this.config.logConfig;
+    const config = this.config;
 
     // Check in order of precedence:
-    // 1. Global level (overrides everything)
-    if (config.globalLevel) {
-      return config.globalLevel;
+    // 1. Service-specific level
+    if (config.serviceLogLevels?.[name]) {
+      return config.serviceLogLevels[name];
     }
 
-    // 2. Service-specific level
-    if (config.serviceLevels?.[name]) {
-      return config.serviceLevels[name];
+    // 2. Default level fallback
+    if (config.defaultLogLevel) {
+      return config.defaultLogLevel;
     }
 
-    // 3. Don't use defaultLevel as it might be too restrictive
-    // Return undefined to let the service use its own default
+    // 3. No fallback - let service use its own default
     return undefined;
   }
 

package/dist/services/service-manager/constants.d.ts

@@ -2,3 +2,5 @@ export const SERVICE_STATE_CHANGED: "service:state-changed";
 export const SERVICE_HEALTH_CHANGED: "service:health-changed";
 export const SERVICE_ERROR: "service:error";
 export const SERVICE_LOG: "service:log";
+export const ANY_LOG_LEVEL: "*";
+export const ANY_SERVICE_NAME: "*";

package/dist/services/service-manager/constants.js

@@ -3,3 +3,6 @@ export const SERVICE_STATE_CHANGED = 'service:state-changed';
 export const SERVICE_HEALTH_CHANGED = 'service:health-changed';
 export const SERVICE_ERROR = 'service:error';
 export const SERVICE_LOG = 'service:log';
+
+export const ANY_LOG_LEVEL = '*';
+export const ANY_SERVICE_NAME = '*';

package/dist/services/service-manager/typedef.d.ts

@@ -38,30 +38,19 @@ export type ServiceManagerConfig = {
      */
     stopTimeout?: number;
     /**
-     * - Initial log level for ServiceManager
+     * - Default log level for new services
      */
-    logLevel?: string;
+    defaultLogLevel?: string;
     /**
-     * - Logging configuration
-     */
-    logConfig?: LogConfig;
-};
-/**
- * Logging configuration
- */
-export type LogConfig = {
-    /**
-     * - Default log level for services
-     */
-    defaultLevel?: string;
-    /**
-     * - Override level for all services
+     * - Initial log level for ServiceManager
      */
-    globalLevel?: string;
+    managerLogLevel?: string;
     /**
-     * - Per-service log levels
+     * Per-service log levels:
+     * - String: "auth:debug,database:info"
+     * - Object: { auth: "debug", database: "info" }
      */
-    serviceLevels?: {
+    serviceLogLevels?: string | {
         [x: string]: string;
     };
 };

package/dist/services/service-manager/typedef.js

@@ -52,17 +52,12 @@
  * @property {boolean} [debug=false] - Debug mode switch
  * @property {boolean} [autoStart=false] - Auto-start services on registration
  * @property {number} [stopTimeout=10000] - Default timeout for stopping services
- * @property {string} [logLevel] - Initial log level for ServiceManager
- * @property {LogConfig} [logConfig={}] - Logging configuration
- */
-
-/**
- * Logging configuration
- *
- * @typedef {Object} LogConfig
- * @property {string} [defaultLevel] - Default log level for services
- * @property {string} [globalLevel] - Override level for all services
- * @property {Object<string, string>} [serviceLevels] - Per-service log levels
+ * @property {string} [defaultLogLevel] - Default log level for new services
+ * @property {string} [managerLogLevel] - Initial log level for ServiceManager
+ * @property {string|Object<string,string>} [serviceLogLevels]
+ *   Per-service log levels:
+ *   - String: "auth:debug,database:info"
+ *   - Object: { auth: "debug", database: "info" }
  */
 
 /**

package/dist/services/service-manager/util.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Parse comma-separated service:level configuration string
+ *
+ * @param {string} configString
+ *   Comma-separated string like "auth:debug,database:info,cache:warn"
+ *
+ * @returns {Object<string, string>} Service name to log level mapping
+ *
+ * @example
+ * const config = parseServiceLogLevels("auth:debug,database:info");
+ * // Returns: { auth: "debug", database: "info" }
+ */
+export function parseServiceLogLevels(configString: string): {
+    [x: string]: string;
+};
+/**
+ * Expand log levels to include higher severity levels
+ *
+ * @param {{[name:string]: string}} serviceLevels
+ *   Service name to log level mapping
+ *
+ * @returns {Object<string, string[]>} Service name to array of log levels
+ *
+ * @example
+ * const levels = expandLogLevels({ auth: "debug", cache: "warn" });
+ * // Returns: {
+ * //   auth: ["debug", "info", "warn", "error"],
+ * //   cache: ["warn", "error"]
+ * // }
+ */
+export function expandLogLevels(serviceLevels: {
+    [name: string]: string;
+}): {
+    [x: string]: string[];
+};

package/dist/services/service-manager/util.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Service Manager utility functions
+ *
+ * Provides utility functions for parsing service configurations, handling
+ * log level hierarchies, and managing service-specific operations.
+ */
+
+import { DEBUG, INFO, WARN, ERROR } from '../../logging/index.js';
+
+/**
+ * Parse comma-separated service:level configuration string
+ *
+ * @param {string} configString
+ *   Comma-separated string like "auth:debug,database:info,cache:warn"
+ *
+ * @returns {Object<string, string>} Service name to log level mapping
+ *
+ * @example
+ * const config = parseServiceLogLevels("auth:debug,database:info");
+ * // Returns: { auth: "debug", database: "info" }
+ */
+export function parseServiceLogLevels(configString) {
+  if (!configString || typeof configString !== 'string') {
+    /** @type {Object<string, string>} */
+    return {};
+  }
+
+  /** @type {Object<string, string>} */
+  const result = {};
+
+  const services = configString.split(',');
+
+  for (const serviceExpression of services) {
+    const trimmed = serviceExpression.trim();
+    if (!trimmed) continue;
+
+    const parts = trimmed.split(':');
+    if (parts.length === 2) {
+      const [serviceName, logLevel] = parts;
+      result[serviceName.trim()] = logLevel.trim();
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Expand log levels to include higher severity levels
+ *
+ * @param {{[name:string]: string}} serviceLevels
+ *   Service name to log level mapping
+ *
+ * @returns {Object<string, string[]>} Service name to array of log levels
+ *
+ * @example
+ * const levels = expandLogLevels({ auth: "debug", cache: "warn" });
+ * // Returns: { 
+ * //   auth: ["debug", "info", "warn", "error"],
+ * //   cache: ["warn", "error"] 
+ * // }
+ */
+export function expandLogLevels(serviceLevels) {
+  /** @type {Object<string, string[]>} */
+  const result = {};
+
+  for (const [serviceName, level] of Object.entries(serviceLevels)) {
+    const levels = [];
+    
+    switch (level.toLowerCase()) {
+      case DEBUG:
+        levels.push(DEBUG, INFO, WARN, ERROR);
+        break;
+      case INFO:
+        levels.push(INFO, WARN, ERROR);
+        break;
+      case WARN:
+        levels.push(WARN, ERROR);
+        break;
+      case ERROR:
+        levels.push(ERROR);
+        break;
+      default:
+        levels.push(level);
+    }
+
+    result[serviceName] = levels;
+  }
+
+  return result;
+}

package/dist/state/machines/finite-state-machine/constants.js

@@ -6,10 +6,10 @@
  * Event emitted when entering a state
  * @type {string}
  */
-export const ENTER = 'enter';
+export const ENTER = '_enter';
 
 /**
  * Event emitted when exiting a state
  * @type {string}
  */
-export const EXIT = 'exit';
+export const EXIT = '_exit';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.4.28",
+	"version": "0.4.30",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"
@@ -52,6 +52,7 @@
 	},
 	"files": [
 		"dist",
+		"CLAUDE.md",
 		"!dist/**/*.test.*",
 		"!dist/**/*.spec.*",
 		"!dist/**/testdata.*",
@@ -76,13 +77,17 @@
 		"@skeletonlabs/skeleton": "^3.1.7",
 		"@steeze-ui/heroicons": "^2.4.2",
 		"@sveltejs/kit": "^2.28.0",
+		"@tailwindcss/postcss": "^4.1.11",
+		"autoprefixer": "^10.4.21",
 		"eslint-plugin-import": "^2.32.0",
 		"jsonwebtoken": "^9.0.0",
 		"pino": "^9.8.0",
 		"pino-pretty": "^13.1.1",
+		"postcss": "^8.5.6",
 		"runed": "^0.31.1",
 		"svelte": "^5.38.1",
 		"svelte-preprocess": "^6.0.3",
+		"tailwindcss": "^4.1.11",
 		"valibot": "^1.1.0",
 		"vite-imagetools": "^8.0.0"
 	},
@@ -98,6 +103,7 @@
 		"@tailwindcss/typography": "^0.5.16",
 		"@testing-library/svelte": "^5.2.8",
 		"@testing-library/user-event": "^14.6.1",
+		"@tailwindcss/postcss": "^4.1.11",
 		"@types/eslint": "^9.6.1",
 		"@types/node": "^24.2.1",
 		"autoprefixer": "^10.4.21",
@@ -128,8 +134,5 @@
 		"vite": "^7.1.2",
 		"vite-imagetools": "^8.0.0",
 		"vitest": "^3.2.4"
-	},
-	"dependencies": {
-		"@tailwindcss/postcss": "^4.1.11"
 	}
 }