@hkdigital/lib-core 0.5.92 → 0.5.94

package/README.md

@@ -3,7 +3,28 @@
 Core library that we use to power up our SvelteKit projects
 
 This is a library for [SvelteKit](https://svelte.dev/) projects.
-It contains common code, base components and documentation that help you with setting up a new project.
+It contains common code, base components and documentation that help
+you with setting up a new project.
+
+## Table of Contents
+
+- [Using the library](#using-the-library)
+  - [Install](#install)
+  - [Peer Dependencies](#peer-dependencies)
+  - [Design System & Configuration](#design-system--configuration)
+  - [Logging System](#logging-system)
+- [Documentation](#documentation)
+  - [Update](#update)
+  - [Available scripts](#available-scripts)
+  - [Import Validation](#import-validation)
+  - [Import Patterns and Export Structure](#import-patterns-and-export-structure)
+  - [CSS Architecture](#css-architecture-appcss)
+  - [Critical: data-theme Attribute](#critical-data-theme-attribute)
+- [Building the library](#building-the-library)
+- [Running the showcase app](#running-the-showcase-app)
+- [Developing](#developing)
+- [Publishing](#publishing)
+- [Contribute](#contribute)
 
 ## Using the library
 
@@ -247,14 +268,47 @@ The library includes a comprehensive logging system that provides:
 
 ## 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
+Comprehensive documentation organized by topic.
+
+### Getting Started
+
+Start here if you're setting up a new project or library:
+
+- **[New project setup](./docs/setup/new-project.md)** - Complete guide
+  for setting up a SvelteKit application with lib-core
+- **[New library setup](./docs/setup/new-lib.md)** - Complete guide for
+  setting up a SvelteKit library with lib-core
+
+### Architecture Guides
+
+Learn how the different systems work together:
+
+- **[Services & logging architecture](./docs/setup/services-logging.md)**
+  - How service management and logging integrate with SvelteKit
+- **[Service patterns](./src/lib/services/PATTERNS.md)** - Best
+  practices and design patterns for implementing services
+- **[Service plugins](./src/lib/services/PLUGINS.md)** - ConfigPlugin
+  and custom plugin development
+
+### API Reference
+
+Detailed API documentation for each module:
+
+- **[Logging](./src/lib/logging/README.md)** - Server and client
+  logging API, log levels, and formatters
+- **[Services](./src/lib/services/README.md)** - ServiceBase and
+  ServiceManager API reference
+- **[Design system](./src/lib/design/README.md)** - Design tokens,
+  theming, and UI utilities
+- **[Vite configuration](./src/lib/config/README.md)** - Build
+  configuration and optimization
+
+### Configuration
+
+Reference documentation for configuration files:
+
+- **[Root config files](./docs/config/root-config-files.md)** - Guide
+  to vite.config.js, tailwind.config.js, and other root configs
 
 ### Update
 

package/dist/browser/info/device.js

@@ -131,13 +131,8 @@ export function getIsPhone() {
  * @returns {boolean} true if mobile device
  */
 export function getIsMobile() {
-  // @ts-ignore
-  if (navigator?.userAgentData?.mobile !== undefined) {
-    // Modern API - most reliable
-    // @ts-ignore
-    return navigator.userAgentData.mobile;
-  }
-
+  // Check Apple devices first - userAgentData.mobile is unreliable for
+  // iPads with M-series chips (reports false despite being mobile)
   if (getIsAppleMobile()) {
     return true;
   }
@@ -146,6 +141,13 @@ export function getIsMobile() {
     return true;
   }
 
+  // @ts-ignore
+  if (navigator?.userAgentData?.mobile !== undefined) {
+    // Modern API - use as fallback
+    // @ts-ignore
+    return navigator.userAgentData.mobile;
+  }
+
   return false;
 }
 

package/dist/config/generators/imagetools.d.ts

@@ -8,6 +8,12 @@
  * @param {number[]} [options.faviconSizes=FAVICON_SIZES]
  * @param {number[]} [options.appleTouchSizes=APPLE_TOUCH_SIZES]
  *
+ * @param {{width: number, height: number}} [options.seoLandscapeSize]
+ *   SEO landscape image size
+ *
+ * @param {{width: number, height: number}} [options.seoSquareSize]
+ *   SEO square image size
+ *
  * @returns {(
  *   entries: [string, string[]][]
  * ) => (Record<string, string | string[]>[])}
@@ -17,6 +23,14 @@ export function generateResponseConfigs(options?: {
     thumbnailWidth?: number | undefined;
     faviconSizes?: number[] | undefined;
     appleTouchSizes?: number[] | undefined;
+    seoLandscapeSize?: {
+        width: number;
+        height: number;
+    } | undefined;
+    seoSquareSize?: {
+        width: number;
+        height: number;
+    } | undefined;
 }): (entries: [string, string[]][]) => (Record<string, string | string[]>[]);
 /**
  * Configures and returns a function that can be used as

package/dist/config/generators/imagetools.js

@@ -21,6 +21,9 @@ const APPLE_TOUCH_SIZES = [
   180  // iPhone retina, iOS home screen
 ];
 
+const SEO_LANDSCAPE_SIZE = { width: 1200, height: 630 };
+const SEO_SQUARE_SIZE = { width: 1200, height: 1200 };
+
 const DEFAULT_PRESETS = {
 	default: {
 		format: 'avif',
@@ -70,6 +73,12 @@ const DEFAULT_PRESETS = {
  * @param {number[]} [options.faviconSizes=FAVICON_SIZES]
  * @param {number[]} [options.appleTouchSizes=APPLE_TOUCH_SIZES]
  *
+ * @param {{width: number, height: number}} [options.seoLandscapeSize]
+ *   SEO landscape image size
+ *
+ * @param {{width: number, height: number}} [options.seoSquareSize]
+ *   SEO square image size
+ *
  * @returns {(
  *   entries: [string, string[]][]
  * ) => (Record<string, string | string[]>[])}
@@ -115,15 +124,25 @@ export function generateResponseConfigs(options) {
 
 		// @ts-ignore
 		const isAppleTouchIcon = !!entries.find(([key]) => key === 'apple-touch-icons');
+
+		// @ts-ignore
+		const isSeoLandscape = !!entries.find(([key]) => key === 'seo-landscape');
+
+		// @ts-ignore
+		const isSeoSquare = !!entries.find(([key]) => key === 'seo-square');
 		// console.log('responsiveConfig found:', !!responsiveConfig);
 
 		const widths = options?.widths ?? DEFAULT_WIDTHS;
 		const faviconSizes = options?.faviconSizes ?? FAVICON_SIZES;
 		const appleTouchSizes = options?.appleTouchSizes ?? APPLE_TOUCH_SIZES;
+		const seoLandscapeSize = options?.seoLandscapeSize ?? SEO_LANDSCAPE_SIZE;
+		const seoSquareSize = options?.seoSquareSize ?? SEO_SQUARE_SIZE;
 
 		delete configPairs.responsive;
 		delete configPairs.favicons;
 		delete configPairs['apple-touch-icons'];
+		delete configPairs['seo-landscape'];
+		delete configPairs['seo-square'];
 
 		// Always include the main image(s) and a thumbnail version
 		const thumbnailConfig = {
@@ -163,6 +182,30 @@ export function generateResponseConfigs(options) {
 			return appleTouchConfigs;
 		}
 
+		// Handle seo-landscape directive - generate landscape SEO image
+
+		if (isSeoLandscape) {
+			return [{
+				...configPairs,
+				w: String(seoLandscapeSize.width),
+				h: String(seoLandscapeSize.height),
+				format: 'jpg',
+				quality: '95'
+			}];
+		}
+
+		// Handle seo-square directive - generate square SEO image
+
+		if (isSeoSquare) {
+			return [{
+				...configPairs,
+				w: String(seoSquareSize.width),
+				h: String(seoSquareSize.height),
+				format: 'jpg',
+				quality: '95'
+			}];
+		}
+
 		if (!responsiveConfig) {
 			// Directive 'responsive' was not set => return original + thumbnail
 			const originalConfig = configPairs; // No 'w' means original dimensions
@@ -227,6 +270,18 @@ export function generateDefaultDirectives(options) {
 			params.set('as', 'metadata');
 		}
 
+		// > Return picture (URL) if directive 'seo-landscape' is set
+
+		if (params.has('seo-landscape')) {
+			params.set('as', 'picture');
+		}
+
+		// > Return picture (URL) if directive 'seo-square' is set
+
+		if (params.has('seo-square')) {
+			params.set('as', 'picture');
+		}
+
 		// > Process presets
 
 		if (presetName) {

package/dist/config/imagetools.d.ts

@@ -84,3 +84,15 @@ declare module '*?apple-touch-icons' {
   const out: ImageSource;
   export default out;
 }
+
+// Generate SEO landscape image (1200x630)
+declare module '*?seo-landscape' {
+  const out: string;
+  export default out;
+}
+
+// Generate SEO square image (1200x1200)
+declare module '*?seo-square' {
+  const out: string;
+  export default out;
+}

package/dist/logging/README.md

@@ -3,6 +3,14 @@
 Universal logging utilities for SvelteKit applications with
 server/client/universal logger factories.
 
+**See also:**
+- **Architecture**: [docs/setup/services-logging.md](../../docs/setup/services-logging.md)
+  - How logging and services work together
+- **Services**: [src/lib/services/README.md](../services/README.md) -
+  Service management system
+- **Main README**: [README.md](../../README.md) - Library overview and
+  setup
+
 ## Installation
 
 ```bash
@@ -182,61 +190,15 @@ export function handleError({ error, event }) {
 }
 ```
 
-### Client Service Integration
-
-When integrating with a service management system, you can set up global 
-error handling and forward service logs to the main logger:
-
-```javascript
-import { ServiceManager } from '@hkdigital/lib-core/services/index.js';
-import { initClientLogger } from '$lib/logging/client.js';
-
-/** @type {ServiceManager} */
-let manager;
-
-export async function initClientServices() {
-  if (!manager) {
-    const logger = initClientLogger();
-
-    // Catch errors and unhandled promise rejections
-    
-    // Log unhandled errors
-    window.addEventListener('error', (event) => {
-      logger.error(event, { url: window.location.pathname });
-      event.preventDefault();
-    });
-
-    // Log unhandled promise rejections
-    window.addEventListener('unhandledrejection', (event) => {
-      logger.error(event, { url: window.location.pathname });
-      // Ignored by Firefox
-      event.preventDefault();
-    });
-
-    manager = new ServiceManager({ debug: true });
-
-    // Listen to all log events and forward them to the logger
-    manager.onLogEvent((logEvent) => {
-      logger.logFromEvent(logEvent);
-    });
-
-    // Register services
-    manager.register(SERVICE_AUDIO, AudioService);
-    manager.register(SERVICE_EVENT_LOG, EventLogService);
-    manager.register(SERVICE_PLAYER_DATA, PlayerDataService);
-  }
+### Service Integration
 
-  await manager.startAll();
-  return manager;
-}
+For integrating logging with the service management system, including
+how to forward service logs to the main logger, see:
 
-export function getManager() {
-  if (!manager) {
-    throw new Error('Client services should be initialised first');
-  }
-  return manager;
-}
-```
+- [Services README](../services/README.md) - ServiceManager log event
+  forwarding
+- [Services & Logging Architecture](../../docs/setup/services-logging.md)
+  - Complete integration examples
 
 ## Development
 

package/dist/meta/README.md

@@ -62,6 +62,12 @@ export const GET = async ({ url }) => {
  *   Supports wildcards (e.g., '*.example.com')
  * @property {string[]} [disallowedPaths]
  *   Paths to block from indexing (e.g., '/admin', '/api/*')
+ * @property {boolean} [allowAiTraining=true]
+ *   Allow AI training bots to crawl content for model training.
+ *   Set to false to block bots like GPTBot, Google-Extended, CCBot, etc.
+ * @property {boolean} [allowAiReading=true]
+ *   Allow AI assistants/chatbots to read content for user responses.
+ *   Set to false to block bots like ChatGPT-User, Claude-Web, etc.
  */
 ```
 
@@ -108,6 +114,54 @@ const config = {
 // Sitemap: https://example.com/sitemap.xml
 ```
 
+**AI bot control:**
+
+```javascript
+// Block all AI bots from training on your content
+const config = {
+  allowedHosts: '*',
+  allowAiTraining: false
+};
+
+// Generates additional blocks:
+// User-agent: GPTBot
+// Disallow: /
+//
+// User-agent: Google-Extended
+// Disallow: /
+// ... (and other AI training bots)
+```
+
+**AI training vs AI reading:**
+
+```javascript
+// Block training but allow reading (ChatGPT can browse, but not train)
+const config = {
+  allowAiTraining: false,  // Blocks GPTBot, Google-Extended, CCBot
+  allowAiReading: true     // Allows ChatGPT-User, Claude-Web
+};
+
+// Block both training and reading
+const config = {
+  allowAiTraining: false,
+  allowAiReading: false
+};
+```
+
+**Blocked AI training bots:**
+- `GPTBot` - OpenAI training
+- `Google-Extended` - Google AI training
+- `CCBot` - Common Crawl
+- `anthropic-ai` - Anthropic training
+- `FacebookBot` - Meta AI training
+- `PerplexityBot` - Perplexity AI training
+- And others (see `src/lib/meta/robots/index.js` for full list)
+
+**Blocked AI reading bots:**
+- `ChatGPT-User` - ChatGPT browsing
+- `Claude-Web` - Claude browsing
+- `cohere-ai` - Cohere browsing
+
 **Sitemap reference:**
 
 Sitemap reference is always included for allowed hosts:
@@ -277,6 +331,44 @@ const robotsConfig = {
 // All hosts → Allow + Sitemap
 ```
 
+### Block AI training but allow search engines
+
+```javascript
+// Protect premium content from AI training while allowing SEO
+const robotsConfig = {
+  allowedHosts: ['mysite.com', 'www.mysite.com'],
+  disallowedPaths: ['/admin'],
+  allowAiTraining: false,  // Block GPTBot, Google-Extended, etc.
+  allowAiReading: true     // Allow ChatGPT browsing (user queries)
+};
+
+// Generates:
+// User-agent: *
+// Allow: /
+// Disallow: /admin
+// Sitemap: https://mysite.com/sitemap.xml
+//
+// User-agent: GPTBot
+// Disallow: /
+//
+// User-agent: Google-Extended
+// Disallow: /
+// ... (other AI training bots)
+```
+
+### Block all AI bots completely
+
+```javascript
+// Block both AI training and AI reading/browsing
+const robotsConfig = {
+  allowedHosts: ['mysite.com'],
+  allowAiTraining: false,
+  allowAiReading: false
+};
+
+// Blocks: GPTBot, Google-Extended, CCBot, ChatGPT-User, Claude-Web, etc.
+```
+
 ### Complex sitemap configuration
 
 ```javascript

package/dist/meta/components/Favicons.svelte

@@ -0,0 +1,30 @@
+<script>
+  /**
+   * Favicons component
+   *
+   * Generates favicon and apple-touch-icon links for browsers and PWAs.
+   *
+   * @typedef {import('../typedef.js').MetaConfig} MetaConfig
+   */
+
+  /** @type {{ config: MetaConfig }} */
+  let { config } = $props();
+
+  const { faviconImages, appleTouchIcons } = config;
+</script>
+
+<svelte:head>
+  <!-- Basic favicon configuration -->
+  {#each faviconImages as img}
+    <link
+      rel="icon"
+      type="image/png"
+      sizes="{img.width}x{img.width}"
+      href={img.src}
+    />
+  {/each}
+
+  {#each appleTouchIcons as img}
+    <link rel="apple-touch-icon" sizes="{img.width}x{img.width}" href={img.src} />
+  {/each}
+</svelte:head>

package/dist/meta/components/Favicons.svelte.d.ts

@@ -0,0 +1,103 @@
+export default Favicons;
+type Favicons = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const Favicons: import("svelte").Component<{
+    config: import("../config.typedef.js").MetaConfig;
+}, {}, "">;
+type $$ComponentProps = {
+    config: {
+        /**
+         * - Full app name
+         */
+        name: string;
+        /**
+         * - Short app name (max 12 characters)
+         */
+        shortName: string;
+        /**
+         * - App description for search engines
+         *
+         * Language and locale
+         */
+        description: string;
+        /**
+         *   Language configurations
+         */
+        languages: Record<string, {
+            lang: string;
+            locale: string;
+        }>;
+        /**
+         * - Default language code
+         */
+        defaultLanguage: string;
+        /**
+         * - Default locale
+         *
+         * PWA theme and colors
+         */
+        defaultLocale: string;
+        /**
+         * - Theme color
+         */
+        backgroundAndThemeColor: string;
+        /**
+         * - Theme color for browser UI
+         */
+        themeColor: string;
+        /**
+         * - Background color
+         */
+        backgroundColor: string;
+        /**
+         * - iOS status bar style
+         */
+        statusBarStyle: string;
+        /**
+         * - Screen orientation
+         */
+        orientation: string;
+        /**
+         * - Disable pinch-to-zoom
+         *
+         * SEO images
+         */
+        disablePageZoom: boolean;
+        /**
+         * - Landscape SEO image URL (1200×630)
+         */
+        SeoImageLandscape?: string | undefined;
+        /**
+         * - Square SEO image URL (1200×1200)
+         *
+         * Favicon images (processed by imagetools)
+         */
+        SeoImageSquare?: string | undefined;
+        /**
+         *   Processed favicon images
+         */
+        faviconImages: Array<{
+            src: string;
+            width: number;
+        }>;
+        /**
+         *   Processed apple-touch-icon images
+         *
+         * Site configuration
+         */
+        appleTouchIcons: Array<{
+            src: string;
+            width: number;
+        }>;
+        /**
+         *   Routes for sitemap.xml
+         */
+        siteRoutes: import("../typedef.js").SitemapRoute[];
+        /**
+         *   Robots.txt configuration
+         */
+        robotsConfig: import("../typedef.js").RobotsConfig;
+    };
+};

package/dist/meta/components/PWA.svelte

@@ -0,0 +1,51 @@
+<script>
+  import { onMount } from 'svelte';
+
+  /**
+   * PWA component
+   *
+   * Generates Progressive Web App meta tags and viewport configuration.
+   *
+   * @typedef {import('../typedef.js').MetaConfig} MetaConfig
+   */
+
+  /** @type {{ config: MetaConfig }} */
+  let { config } = $props();
+
+  const { themeColor, statusBarStyle, name, shortName, disablePageZoom } =
+    config;
+
+  let shouldSetTitle = $state(false);
+
+  onMount(() => {
+    // Check if title element exists and has content
+    const titleElement = document.querySelector('title');
+    const hasTitle = titleElement && titleElement.textContent.trim() !== '';
+
+    if (!hasTitle) {
+      shouldSetTitle = true;
+    }
+  });
+</script>
+
+<svelte:head>
+  {#if shouldSetTitle}
+    <title>{name}</title>
+  {/if}
+
+  {#if !disablePageZoom}
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  {:else}
+    <meta name="viewport"
+         content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no, width=device-width, viewport-fit=cover" />
+  {/if}
+
+  <meta name="theme-color" content="{themeColor}">
+  <link rel="manifest" href="/manifest.json">
+
+  <meta name="mobile-web-app-capable" content="yes">
+
+  <!-- iOS-specific meta tags -->
+  <meta name="apple-mobile-web-app-status-bar-style" content="{statusBarStyle}">
+  <meta name="apple-mobile-web-app-title" content="{shortName}">
+</svelte:head>