@hkdigital/lib-core 0.4.23 → 0.4.25

package/dist/state/{classes → machines}/loading-state-machine/constants.js

@@ -5,6 +5,7 @@ export const STATE_LOADED = 'loaded';
 
 export const STATE_CANCELLED = 'cancelled';
 export const STATE_ERROR = 'error';
+export const STATE_TIMEOUT = 'timeout';
 
 // > Signals
 
@@ -14,3 +15,4 @@ export const CANCEL = 'cancel';
 export const ERROR = 'error';
 export const LOADED = 'loaded';
 export const UNLOAD = 'unload';
+export const TIMEOUT = 'timeout';

package/dist/state/machines/typedef.d.ts

@@ -0,0 +1 @@
+export * from "./finite-state-machine/typedef.js";

package/dist/state/machines/typedef.js

@@ -0,0 +1 @@
+export * from './finite-state-machine/typedef.js';

package/dist/state/machines.d.ts

@@ -0,0 +1,2 @@
+export * from "./machines/finite-state-machine/index.js";
+export * from "./machines/loading-state-machine/index.js";

package/dist/state/machines.js

@@ -0,0 +1,2 @@
+export * from './machines/finite-state-machine/index.js';
+export * from './machines/loading-state-machine/index.js';

package/dist/state/typedef.d.ts

@@ -1,3 +1,4 @@
 export * from "./context/typedef.js";
+export * from "./machines/typedef.js";
 declare const _default: {};
 export default _default;

package/dist/state/typedef.js

@@ -1,3 +1,4 @@
 export * from './context/typedef.js';
+export * from './machines/typedef.js';
 
 export default {};

package/dist/ui/components/game-box/README.md

@@ -0,0 +1,245 @@
+# GameBox Component
+
+A responsive container component designed for creating games and fullscreen
+applications with adaptive scaling, orientation handling, and mobile PWA
+support.
+
+## Features
+
+- **Responsive Layout**: Automatically adapts to landscape and portrait
+  orientations
+- **Aspect Ratio Control**: Configurable aspect ratios for different
+  orientations
+- **Mobile PWA Support**: Handles iOS Safari PWA quirks and fullscreen modes
+- **Dynamic Scaling**: Optional design system scaling based on container size
+- **Fullscreen Management**: Built-in fullscreen request handling
+- **Device Detection**: Automatic mobile and OS detection
+
+## Basic Usage
+
+```svelte
+<script>
+  import { GameBox } from '$lib/ui/components/game-box/index.js';
+</script>
+
+<GameBox
+  aspectOnLandscape={16/9}
+  aspectOnPortrait={9/16}
+  snippetLandscape={landscapeContent}
+  snippetPortrait={portraitContent}
+/>
+
+{#snippet landscapeContent({ gameWidth, gameHeight, isMobile })}
+  <div>Game content for landscape - {gameWidth}x{gameHeight}</div>
+{/snippet}
+
+{#snippet portraitContent({ gameWidth, gameHeight, isMobile })}
+  <div>Game content for portrait - {gameWidth}x{gameHeight}</div>
+{/snippet}
+```
+
+## Props
+
+### Styling Props
+- `base?: string` - Base CSS classes
+- `bg?: string` - Background CSS classes  
+- `classes?: string` - Additional CSS classes
+- `style?: string` - Inline styles
+
+### Layout Props
+- `aspectOnLandscape?: number` - Aspect ratio for landscape mode (e.g., 16/9)
+- `aspectOnPortrait?: number` - Aspect ratio for portrait mode (e.g., 9/16)
+- `marginLeft?: number` - Left margin in pixels (default: 0)
+- `marginRight?: number` - Right margin in pixels (default: 0)
+- `marginTop?: number` - Top margin in pixels (default: 0)
+- `marginBottom?: number` - Bottom margin in pixels (default: 0)
+- `center?: boolean` - Center the game box in viewport
+
+### Scaling Props
+- `enableScaling?: boolean` - Enable design system scaling (default: false)
+- `designLandscape?: {width: number, height: number}` - Design dimensions
+  for landscape (default: {width: 1920, height: 1080})
+- `designPortrait?: {width: number, height: number}` - Design dimensions
+  for portrait (default: {width: 1920, height: 1080})
+- `clamping?: object` - Scaling limits for different elements
+
+### Snippet Props
+- `snippetLandscape?: Snippet` - Content for landscape orientation
+- `snippetPortrait?: Snippet` - Content for portrait orientation
+- `snippetRequireFullscreen?: Snippet` - Content when fullscreen is required
+- `snippetInstallOnHomeScreen?: Snippet` - Content for home screen install
+  prompt
+
+## Snippet Parameters
+
+All snippets receive these parameters:
+
+```js
+{
+  isMobile: boolean,          // Is running on mobile device
+  os: 'Android'|'iOS',        // Operating system
+  isFullscreen: boolean,      // Is in fullscreen mode
+  isDevMode: boolean,         // Is in development mode
+  requestDevmode: function,   // Function to enable dev mode
+  requestFullscreen: function, // Function to request fullscreen
+  gameWidth: number,          // Calculated game width
+  gameHeight: number          // Calculated game height
+}
+```
+
+## Examples
+
+### Simple Game Container
+
+```svelte
+<GameBox
+  aspectOnLandscape={16/9}
+  aspectOnPortrait={9/16}
+  center={true}
+  snippetLandscape={gameContent}
+  snippetPortrait={gameContent}
+/>
+
+{#snippet gameContent({ gameWidth, gameHeight })}
+  <div class="game-area bg-surface-900 rounded-lg p-20up">
+    <h1 class="type-heading-h1 text-center mb-20up">My Game</h1>
+    <div class="game-content" style="width: 100%; height: 100%;">
+      Game content goes here
+    </div>
+  </div>
+{/snippet}
+```
+
+### With Fullscreen Requirement
+
+```svelte
+<GameBox
+  aspectOnLandscape={21/9}
+  center={true}
+  snippetLandscape={gameContent}
+  snippetRequireFullscreen={fullscreenPrompt}
+/>
+
+{#snippet gameContent({ gameWidth, gameHeight, isFullscreen })}
+  <div class="cinematic-game">
+    Ultra-wide cinematic game experience
+  </div>
+{/snippet}
+
+{#snippet fullscreenPrompt({ requestFullscreen })}
+  <div class="fullscreen-prompt text-center">
+    <h2 class="type-heading-h2 mb-16bt">Fullscreen Required</h2>
+    <p class="type-base-md mb-20bt">
+      This game requires fullscreen mode for the best experience.
+    </p>
+    <button class="btn-primary" onclick={requestFullscreen}>
+      Enter Fullscreen
+    </button>
+  </div>
+{/snippet}
+```
+
+### With Scaling Enabled
+
+```svelte
+<GameBox
+  aspectOnLandscape={16/9}
+  enableScaling={true}
+  designLandscape={{ width: 1920, height: 1080 }}
+  clamping={{
+    ui: { min: 0.5, max: 1.5 },
+    textBase: { min: 0.8, max: 1.2 },
+    textHeading: { min: 0.75, max: 2 },
+    textUi: { min: 0.6, max: 1.1 }
+  }}
+  snippetLandscape={scaledContent}
+/>
+
+{#snippet scaledContent()}
+  <div class="game-ui">
+    <!-- UI elements will automatically scale based on container size -->
+    <div class="hud">
+      <span class="type-ui-sm">Score: 1000</span>
+    </div>
+  </div>
+{/snippet}
+```
+
+### Mobile-Specific Handling
+
+```svelte
+<GameBox
+  aspectOnLandscape={16/9}
+  aspectOnPortrait={9/16}
+  snippetLandscape={landscapeGame}
+  snippetPortrait={portraitGame}
+  snippetInstallOnHomeScreen={installPrompt}
+/>
+
+{#snippet landscapeGame({ isMobile, os })}
+  <div class="landscape-game">
+    {#if isMobile}
+      <div class="mobile-controls">
+        <!-- Touch controls for mobile -->
+      </div>
+    {:else}
+      <div class="desktop-controls">
+        <!-- Keyboard/mouse controls for desktop -->
+      </div>
+    {/if}
+  </div>
+{/snippet}
+
+{#snippet portraitGame({ isMobile })}
+  <div class="portrait-game">
+    <!-- Optimized for portrait mobile gameplay -->
+  </div>
+{/snippet}
+
+{#snippet installPrompt({ os })}
+  <div class="install-prompt text-center">
+    <h2 class="type-heading-h2 mb-16bt">Install App</h2>
+    <p class="type-base-md mb-20bt">
+      {#if os === 'iOS'}
+        Tap the share button and select "Add to Home Screen"
+      {:else}
+        Install this app for the best gaming experience
+      {/if}
+    </p>
+  </div>
+{/snippet}
+```
+
+## CSS Custom Properties
+
+The component exposes these CSS custom properties:
+
+- `--game-width`: Current game width in pixels
+- `--game-height`: Current game height in pixels
+
+These can be used in your CSS for responsive styling:
+
+```css
+.game-element {
+  width: calc(var(--game-width) * 0.5);
+  height: calc(var(--game-height) * 0.2);
+}
+```
+
+## Mobile PWA Considerations
+
+The component includes special handling for mobile PWAs:
+
+- **iOS Safari PWA**: Handles viewport quirks and orientation changes
+- **Fullscreen Detection**: Properly detects PWA fullscreen mode
+- **Screen Orientation**: Listens for orientation changes and updates layout
+- **No Scroll**: Automatically prevents scrolling when active
+
+## Development Mode
+
+The component automatically enables development mode when:
+- Running on `localhost`
+- Called via `requestDevmode()` function
+
+In development mode, fullscreen and installation requirements are bypassed
+for easier testing.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.4.23",
+	"version": "0.4.25",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"

package/dist/logging/internal/adapters/pino.js__

@@ -1,260 +0,0 @@
-/**
- * Pino adapter for server-side logging
- */
-import pino from 'pino';
-import { dev } from '$app/environment';
-
-import {
-  detectErrorMeta,
-  findRelevantFrameIndex,
-  formatErrorDisplay
-} from './formatting.js';
-
-/**
- * Pino adapter that bridges Logger events to pino
- */
-export class PinoAdapter {
-  #projectRoot = null;
-
-  /**
-   * Create a new PinoAdapter
-   *
-   * @param {Object} [options] - Pino configuration options
-   */
-  constructor(options = {}) {
-    // Determine project root once for stack trace cleaning
-    this.#projectRoot = import.meta.env.VITE_PROJECT_ROOT || process.cwd();
-    const baseOptions = {
-      serializers: {
-        errors: (err) => {
-
-          /** @type {import('./typedef').ErrorSummary[]} */
-          const chain = [];
-          let loggedAt = null;
-
-          let current = err;
-          let isFirst = true;
-
-          while (current && current instanceof Error) {
-            // Check if this is the first error and it's a LoggerError - extract logging context
-            if (isFirst && current.name === 'LoggerError') {
-              if (current.stack) {
-                const cleanedStackString = this.#cleanStackTrace(current.stack);
-                const cleanedStackArray = cleanedStackString
-                  .split('\n')
-                  .map((line) => line.trim())
-                  .filter(
-                    (line) =>
-                      line && line !== current.name + ': ' + current.message
-                  );
-
-                // For LoggerError, we know it's a logger.error call, so find the relevant frame
-                const loggerErrorIndex = cleanedStackArray.findIndex(frame =>
-                  (frame.includes('Logger.error') && frame.includes('logger/Logger.js')) ||
-                  (frame.includes('error@') && frame.includes('logger/Logger.js'))
-                );
-
-                if (loggerErrorIndex >= 0 && loggerErrorIndex + 1 < cleanedStackArray.length) {
-                  const relevantFrame = cleanedStackArray[loggerErrorIndex + 1];
-
-                  // Extract function name from the relevant frame
-                  // const functionName = parseFunctionName(relevantFrame);
-
-                  // const errorType = functionName ? `logger.error in ${functionName}` : 'logger.error';
-                  loggedAt = relevantFrame.slice(3); // remove "at "
-                }
-              }
-
-              // Skip the LoggerError and move to the actual error
-              current = current.cause;
-              isFirst = false;
-              continue;
-            }
-            /** @type {import('./typedef').ErrorSummary} */
-            const serialized = {
-              name: current.name,
-              message: current.message
-            };
-
-            // Add error metadata for structured logging and terminal display
-            if (current.stack) {
-              // Convert cleaned stack string to array format expected by formatting functions
-              const cleanedStackString = this.#cleanStackTrace(current.stack);
-              const cleanedStackArray = cleanedStackString
-                .split('\n')
-                .map((line) => line.trim())
-                .filter(
-                  (line) =>
-                    line && line !== current.name + ': ' + current.message
-                );
-
-              const errorMeta = detectErrorMeta(current, cleanedStackArray);
-              const relevantFrameIndex = findRelevantFrameIndex(
-                current,
-                cleanedStackArray
-              );
-
-              serialized.meta = errorMeta;
-              serialized.errorType = formatErrorDisplay(errorMeta);
-
-              // Include stack frames for terminal display
-              serialized.stackFrames = cleanedStackArray
-                .slice(0, 9)
-                .map((frame, index) => {
-                  const marker = index === relevantFrameIndex ? '→' : ' ';
-
-                  return `${marker} ${frame}`;
-                });
-            }
-
-            // Include HttpError-specific properties
-            const httpError = /** @type {import('$lib/network/errors.js').HttpError} */ (current);
-            if (httpError.status !== undefined) {
-              serialized.status = httpError.status;
-            }
-            if (httpError.details !== undefined) {
-              serialized.details = httpError.details;
-            }
-
-            chain.push(serialized);
-            current = current.cause;
-            isFirst = false;
-          }
-
-          return loggedAt ? { chain, loggedAt } : chain;
-        }
-      }
-    };
-
-    // Add error handling for missing pino-pretty in dev
-    if ( dev) {
-      const devOptions = {
-        level: 'debug',
-        transport: {
-          target: 'pino-pretty',
-          options: {
-            colorize: true,
-            ignore: 'hostname,pid'
-          }
-        }
-      };
-
-      try {
-        this.pino = pino({ ...baseOptions, ...devOptions, ...options });
-      } catch (error) {
-        if (
-          error.message.includes('Cannot find module') &&
-          error.message.includes('pino-pretty')
-        ) {
-          const errorMessage = `
-╭─────────────────────────────────────────────────────────────╮
-│                     Missing Dependency                      │
-├─────────────────────────────────────────────────────────────┤
-│  'pino-pretty' is required for development logging          │
-│  Install it with: pnpm add -D pino-pretty                   │
-╰─────────────────────────────────────────────────────────────╯`;
-          console.error(errorMessage);
-          throw new Error('pino-pretty is required for development mode');
-        }
-        throw error;
-      }
-    } else {
-      this.pino = pino({ ...baseOptions, ...options });
-    }
-  }
-
-  /**
-   * Clean stack trace by removing project root path and simplifying node_modules
-   *
-   * @param {string} stack - Original stack trace
-   * @returns {string} Cleaned stack trace
-   */
-  #cleanStackTrace(stack) {
-    if (!stack || !this.#projectRoot) {
-      return stack;
-    }
-
-    let cleaned = stack;
-
-    // Escape special regex characters in the project root path
-    const escapedRoot = this.#projectRoot.replace(
-      /[.*+?^${}()|[\]\\]/g,
-      '\\$&'
-    );
-
-    // Replace project root path with relative path, handling file:// protocol
-    // Match both regular paths and file:// URLs
-    const rootRegex = new RegExp(
-      `(\\s+at\\s+.*\\()(file://)?${escapedRoot}[\\/\\\\]`,
-      'g'
-    );
-    cleaned = cleaned.replace(rootRegex, '$1');
-
-    // Simplify pnpm paths: node_modules/.pnpm/package@version_deps/node_modules/package
-    // becomes: node_modules/package
-    const pnpmRegex =
-      /node_modules\/\.pnpm\/([^@\/]+)@[^\/]+\/node_modules\/\1/g;
-    cleaned = cleaned.replace(pnpmRegex, 'node_modules/$1');
-
-    // Also handle cases where the package name might be different in the final path
-    const pnpmRegex2 = /node_modules\/\.pnpm\/[^\/]+\/node_modules\/([^\/]+)/g;
-    cleaned = cleaned.replace(pnpmRegex2, 'node_modules/$1');
-
-    return cleaned;
-  }
-
-  /**
-   * Handle log events from Logger
-   *
-   * @param {Object} logEvent - Log event from Logger
-   */
-  handleLog(logEvent) {
-    const { level, message, details, source, timestamp } = logEvent;
-
-    const logData = {
-      source,
-      timestamp
-    };
-
-    // Check if details contains an error and promote it to err property for pino serializer
-    if (details) {
-      if (details instanceof Error) {
-        // details is directly an error
-        logData.err = details;
-      } else if (details.error instanceof Error) {
-        // details has an error property
-        logData.err = details.error;
-        // Include other details except the error
-        // eslint-disable-next-line no-unused-vars
-        const { error, ...otherDetails } = details;
-        if (Object.keys(otherDetails).length > 0) {
-          logData.details = otherDetails;
-        }
-      } else {
-        // No error found in details, include all details
-        logData.details = details;
-      }
-    }
-
-    // Check if we have loggedAt info from the serializer
-    if (logData.err && typeof logData.err === 'object' && logData.err.loggedAt) {
-      logData.loggedAt = logData.err.loggedAt;
-      logData.err = logData.err.chain;
-    }
-
-    this.pino[level](logData, message);
-  }
-
-  /**
-   * Create a child logger with additional context
-   *
-   * @param {Object} context - Additional context data
-   * @returns {PinoAdapter} New adapter instance with context
-   */
-  child(context) {
-    const childPino = this.pino.child(context);
-    const adapter = new PinoAdapter();
-    adapter.pino = childPino;
-    return adapter;
-  }
-}

package/dist/state/classes/finite-state-machine/FiniteStateMachine.svelte.js

@@ -1,133 +0,0 @@
-/**
- * Initial code borrowed from:
- *
- * @see {@link https://runed.dev/docs/utilities/finite-state-machine}
- */
-
-/**
- * Check if the value is valid meta data
- *
- * @param {any} meta
- */
-export function isLifecycleFnMeta(meta) {
-  return (
-    !!meta &&
-    typeof meta === 'object' &&
-    'to' in meta &&
-    'from' in meta &&
-    'event' in meta &&
-    'args' in meta
-  );
-}
-
-/**
- * Defines a Finite State Machine
- */
-export default class FiniteStateMachine {
-  #current = $state();
-  states;
-  #timeout = {};
-
-  /**
-   * Constructor
-   *
-   * @param {string} initial
-   * @param {{ [key: string]: { [key: string]: (string|((...args: any[])=>void)) } }} states
-   */
-  constructor(initial, states) {
-    this.#current = initial;
-    this.states = states;
-
-    // synthetically trigger _enter for the initial state.
-    this.#dispatch('_enter', {
-      from: null,
-      to: initial,
-      event: null,
-      args: []
-    });
-  }
-
-  /**
-   * Transition to new state
-   *
-   * @param {string} newState
-   * @param {string} event
-   * @param {any[]} [args]
-   */
-  #transition(newState, event, args) {
-    const metadata = { from: this.#current, to: newState, event, args };
-    this.#dispatch('_exit', metadata);
-    this.#current = newState;
-    this.#dispatch('_enter', metadata);
-  }
-
-  /**
-   * Dispatch an event
-   *
-   * @param {string} event
-   * @param {any[]} args
-   */
-  #dispatch(event, ...args) {
-    const action =
-      this.states[this.#current]?.[event] ?? this.states['*']?.[event];
-    if (action instanceof Function) {
-      if (event === '_enter' || event === '_exit') {
-        if (isLifecycleFnMeta(args[0])) {
-          action(args[0]);
-        } else {
-          console.warn(
-            'Invalid metadata passed to lifecycle function of the FSM.'
-          );
-        }
-      } else {
-        return action(...args);
-      }
-    } else if (typeof action === 'string') {
-      return action;
-    } else if (event !== '_enter' && event !== '_exit') {
-      console.warn(
-        'No action defined for event',
-        event,
-        'in state',
-        this.#current
-      );
-    }
-  }
-  /**
-   * Triggers a new event and returns the new state.
-   *
-   * @param {string} event
-   * @param {any[]} args
-   */
-  send(event, ...args) {
-    const newState = this.#dispatch(event, ...args);
-    if (newState && newState !== this.#current) {
-      this.#transition(newState, event, args);
-    }
-
-    return this.#current;
-  }
-  /**
-   * Debounces the triggering of an event.
-   *
-   * @param {number} wait
-   * @param {string} event
-   * @param {any[]} args
-   */
-  async debounce(wait = 500, event, ...args) {
-    if (this.#timeout[event]) {
-      clearTimeout(this.#timeout[event]);
-    }
-    return new Promise((resolve) => {
-      this.#timeout[event] = setTimeout(() => {
-        delete this.#timeout[event];
-        resolve(this.send(event, ...args));
-      }, wait);
-    });
-  }
-
-  /** The current state. */
-  get current() {
-    return this.#current;
-  }
-}

package/dist/state/classes/loading-state-machine/LoadingStateMachine.svelte.d.ts

@@ -1,12 +0,0 @@
-/**
- * extends FiniteStateMachine<StatesT, EventsT>
- */
-export default class LoadingStateMachine extends FiniteStateMachine {
-    constructor();
-    /** @type {(( state: string )=>void)|null} */
-    onenter: ((state: string) => void) | null;
-    /** The last error */
-    get error(): Error;
-    #private;
-}
-import FiniteStateMachine from '../finite-state-machine/FiniteStateMachine.svelte.js';