@kkuffour/solid-moderation-plugin 0.2.3 → 0.3.0

package/src/ModerationHandler.ts

@@ -0,0 +1,189 @@
+import { OperationHandler, getLoggerFor, ForbiddenHttpError, NotFoundHttpError, guardedStreamFrom } from '@solid/community-server';
+import type { OperationHandlerInput, ResponseDescription } from '@solid/community-server';
+import { writeFileSync, unlinkSync } from 'fs';
+import type { SightEngineProvider } from './providers/SightEngineProvider';
+
+export class ModerationHandler extends OperationHandler {
+  private readonly logger = getLoggerFor(this);
+  private readonly client: SightEngineProvider;
+  private readonly enabled: boolean;
+  private readonly imageNudityThreshold: number;
+  private readonly textSexualThreshold: number;
+  private readonly textToxicThreshold: number;
+  private readonly videoNudityThreshold: number;
+
+  public constructor(
+    client: SightEngineProvider,
+    enabled: boolean,
+    imageNudityThreshold: number,
+    textSexualThreshold: number,
+    textToxicThreshold: number,
+    videoNudityThreshold: number,
+  ) {
+    super();
+    this.client = client;
+    this.enabled = enabled;
+    this.imageNudityThreshold = imageNudityThreshold;
+    this.textSexualThreshold = textSexualThreshold;
+    this.textToxicThreshold = textToxicThreshold;
+    this.videoNudityThreshold = videoNudityThreshold;
+
+    this.logger.info('ModerationHandler initialized');
+    this.logger.info(`  Enabled: ${enabled}`);
+    this.logger.info(`  Thresholds: image=${imageNudityThreshold}, text=${textSexualThreshold}/${textToxicThreshold}, video=${videoNudityThreshold}`);
+  }
+
+  public async handle({ operation }: OperationHandlerInput): Promise<ResponseDescription> {
+    this.logger.info(`[MODERATION] Handler called: ${operation.method} ${operation.target.path}`);
+    
+    if (!this.enabled) {
+      this.logger.info('[MODERATION] Handler disabled, passing through');
+      throw new NotFoundHttpError();
+    }
+
+    if (!this.shouldModerate(operation)) {
+      this.logger.info(`[MODERATION] Operation not moderatable: ${operation.method}`);
+      throw new NotFoundHttpError();
+    }
+
+    const contentType = operation.body?.metadata.contentType;
+    if (!contentType || !this.isModeratable(contentType)) {
+      this.logger.info(`[MODERATION] Content type not moderatable: ${contentType}`);
+      throw new NotFoundHttpError();
+    }
+
+    this.logger.info(`[MODERATION] Starting moderation: ${operation.method} ${contentType} to ${operation.target.path}`);
+
+    try {
+      this.logger.info('[MODERATION] Reading request body...');
+      const chunks: Buffer[] = [];
+      for await (const chunk of operation.body!.data) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      const buffer = Buffer.concat(chunks);
+      this.logger.info(`[MODERATION] Body read: ${buffer.length} bytes`);
+
+      if (contentType.startsWith('image/')) {
+        this.logger.info('[MODERATION] Calling image moderation...');
+        await this.moderateImage(operation.target.path, buffer, contentType);
+      } else if (contentType.startsWith('video/')) {
+        this.logger.info('[MODERATION] Calling video moderation...');
+        await this.moderateVideo(operation.target.path, buffer, contentType);
+      } else if (contentType.startsWith('text/')) {
+        this.logger.info('[MODERATION] Calling text moderation...');
+        await this.moderateText(operation.target.path, buffer);
+      }
+
+      operation.body!.data = guardedStreamFrom(buffer);
+      this.logger.info(`[MODERATION] ✅ Content APPROVED: ${operation.target.path}`);
+
+    } catch (error: unknown) {
+      if (error instanceof ForbiddenHttpError) {
+        this.logger.warn(`[MODERATION] ❌ Content BLOCKED: ${operation.target.path} - ${(error as Error).message}`);
+        throw error;
+      }
+      this.logger.error(`[MODERATION] ⚠️ Moderation failed: ${(error as Error).message}`);
+      this.logger.warn('[MODERATION] Allowing content through (fail-open policy)');
+    }
+
+    throw new NotFoundHttpError();
+  }
+
+  private shouldModerate(operation: any): boolean {
+    return (operation.method === 'POST' || operation.method === 'PUT' || operation.method === 'PATCH') && 
+           operation.body;
+  }
+
+  private isModeratable(contentType: string): boolean {
+    return contentType.startsWith('image/') || 
+           contentType.startsWith('video/') || 
+           contentType.startsWith('text/');
+  }
+
+  private async moderateImage(path: string, buffer: Buffer, contentType: string): Promise<void> {
+    const tempFile = `/tmp/moderation_${Date.now()}.${this.getFileExtension(contentType)}`;
+    this.logger.info(`[MODERATION] Writing temp file: ${tempFile}`);
+    writeFileSync(tempFile, buffer);
+
+    try {
+      this.logger.info('[MODERATION] Calling SightEngine API for image analysis...');
+      const result = await this.client.analyzeImage(tempFile);
+      this.logger.info(`[MODERATION] SightEngine response: ${JSON.stringify(result)}`);
+
+      if (result.nudity?.raw && result.nudity.raw > this.imageNudityThreshold) {
+        this.logger.warn(`[MODERATION] Image BLOCKED: ${path} - nudity ${result.nudity.raw.toFixed(2)} > ${this.imageNudityThreshold}`);
+        throw new ForbiddenHttpError(`Image contains inappropriate content (nudity: ${result.nudity.raw.toFixed(2)})`);
+      }
+      this.logger.info(`[MODERATION] Image passed: nudity ${result.nudity?.raw?.toFixed(2) || 'N/A'} <= ${this.imageNudityThreshold}`);
+    } finally {
+      try {
+        unlinkSync(tempFile);
+        this.logger.info(`[MODERATION] Cleaned up temp file: ${tempFile}`);
+      } catch {
+        this.logger.warn(`[MODERATION] Failed to cleanup: ${tempFile}`);
+      }
+    }
+  }
+
+  private async moderateVideo(path: string, buffer: Buffer, contentType: string): Promise<void> {
+    const tempFile = `/tmp/moderation_${Date.now()}.${this.getFileExtension(contentType)}`;
+    this.logger.info(`[MODERATION] Writing temp file: ${tempFile}`);
+    writeFileSync(tempFile, buffer);
+
+    try {
+      this.logger.info('[MODERATION] Calling SightEngine API for video analysis...');
+      const result = await this.client.analyzeVideo(tempFile);
+      this.logger.info(`[MODERATION] SightEngine response: ${JSON.stringify(result)}`);
+
+      if (result.nudity?.raw && result.nudity.raw > this.videoNudityThreshold) {
+        this.logger.warn(`[MODERATION] Video BLOCKED: ${path} - nudity ${result.nudity.raw.toFixed(2)} > ${this.videoNudityThreshold}`);
+        throw new ForbiddenHttpError(`Video contains inappropriate content (nudity: ${result.nudity.raw.toFixed(2)})`);
+      }
+      this.logger.info(`[MODERATION] Video passed: nudity ${result.nudity?.raw?.toFixed(2) || 'N/A'} <= ${this.videoNudityThreshold}`);
+    } finally {
+      try {
+        unlinkSync(tempFile);
+        this.logger.info(`[MODERATION] Cleaned up temp file: ${tempFile}`);
+      } catch {
+        this.logger.warn(`[MODERATION] Failed to cleanup: ${tempFile}`);
+      }
+    }
+  }
+
+  private async moderateText(path: string, buffer: Buffer): Promise<void> {
+    const text = buffer.toString('utf-8');
+    this.logger.info(`[MODERATION] Text length: ${text.length} chars`);
+    
+    this.logger.info('[MODERATION] Calling SightEngine API for text analysis...');
+    const result = await this.client.analyzeText(text);
+    this.logger.info(`[MODERATION] SightEngine response: ${JSON.stringify(result)}`);
+
+    const violations: string[] = [];
+
+    if (result.sexual > this.textSexualThreshold) {
+      violations.push(`sexual (${result.sexual.toFixed(2)} > ${this.textSexualThreshold})`);
+    }
+
+    if (result.toxic > this.textToxicThreshold) {
+      violations.push(`toxic (${result.toxic.toFixed(2)} > ${this.textToxicThreshold})`);
+    }
+
+    if (violations.length > 0) {
+      this.logger.warn(`[MODERATION] Text BLOCKED: ${path} - ${violations.join(', ')}`);
+      throw new ForbiddenHttpError(`Text contains inappropriate content: ${violations.join(', ')}`);
+    }
+    this.logger.info(`[MODERATION] Text passed: sexual ${result.sexual.toFixed(2)}, toxic ${result.toxic.toFixed(2)}`);
+  }
+
+  private getFileExtension(contentType: string): string {
+    const map: Record<string, string> = {
+      'image/jpeg': 'jpg',
+      'image/png': 'png',
+      'image/gif': 'gif',
+      'image/webp': 'webp',
+      'video/mp4': 'mp4',
+      'video/webm': 'webm',
+    };
+    return map[contentType] || 'bin';
+  }
+}

package/src/index.ts

@@ -1,7 +1,2 @@
-export * from './ModerationOperationHandler';
-export * from './ModerationResourceStore';
-export * from './ModerationConfig';
-export * from './ModerationStore';
-export * from './ModerationRecord';
-export * from './ModerationMixin';
+export * from './ModerationHandler';
 export * from './providers/SightEngineProvider';

package/ARCHITECTURE.md

@@ -1,52 +0,0 @@
-# Architecture Decision: ResourceStore vs OperationHandler
-
-## Branch History
-
-### `main` branch (v0.1.0 - v0.1.2)
-**Approach**: OperationHandler wrapping  
-**Status**: ❌ Does not work  
-**Reason**: Components.js cannot resolve cross-module component overrides. When trying to override `urn:solid-server:default:PutOperationHandler` with a type from an external npm package, Components.js looks for the type in the CSS module, not the plugin module.
-
-**Key Learning**: Components.js uses module-scoped component resolution. External plugins cannot override core CSS handler IDs.
-
-### `resourcestore-approach` branch (v0.2.0+)
-**Approach**: ResourceStore wrapping  
-**Status**: 🚧 In development  
-**Strategy**: Wrap `urn:solid-server:default:ResourceStore` instead of individual operation handlers.
-
-## Why ResourceStore Works
-
-1. **Single interception point**: All write operations (PUT/POST/PATCH) call `ResourceStore.setRepresentation()`
-2. **Designed for swapping**: CSS architecture expects ResourceStore to be configurable/replaceable
-3. **Proper abstraction boundary**: ResourceStore is the storage layer interface
-4. **Components.js compatible**: ResourceStore wrapping is a supported pattern
-
-## Implementation Plan
-
-```
-Request Flow:
-HTTP Request → OperationHandler → ResourceStore → Backend
-                                        ↑
-                                   INTERCEPT HERE
-```
-
-### Core Changes
-- Create `ModerationResourceStore` implementing `ResourceStore` interface
-- Wrap original store and intercept `setRepresentation()`
-- Moderate content before passing to wrapped store
-- Delegate all read operations (getRepresentation, etc.)
-
-### Config Pattern
-```json
-{
-  "@id": "urn:solid-server:default:ResourceStore",
-  "@type": "ModerationResourceStore",
-  "source": { "@id": "urn:solid-server:default:ResourceStore_Original" }
-}
-```
-
-## Version Strategy
-
-- **v0.1.x**: OperationHandler approach (archived, doesn't work)
-- **v0.2.x**: ResourceStore approach (current development)
-- Users can install specific versions if needed: `npm install @kkuffour/solid-moderation-plugin@0.1.2`

package/CONFIG-GUIDE.md

@@ -1,49 +0,0 @@
-# Configuration Guide
-
-## Understanding the Configuration Files
-
-### `config/default.json` (Production - Installed with npm)
-- Located in `node_modules/@solid/moderation-plugin/config/default.json` after installation
-- Contains the complete moderation setup with default thresholds
-- Imported by users in their CSS config using: `"@solid/moderation-plugin:config/default.json"`
-- **This is what production users import**
-
-### `config-with-moderation.json` (Local Testing Only)
-- Located in the plugin source directory
-- Used for testing the plugin locally before publishing
-- Points to local files, not npm package
-- **Not included in npm package**
-
-## For Production Users
-
-When you install the plugin via npm, you create a config file in **your CSS project**:
-
-```json
-{
-  "@context": "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^7.0.0/components/context.jsonld",
-  "import": [
-    "css:config/file.json",
-    "@solid/moderation-plugin:config/default.json"
-  ]
-}
-```
-
-Then run:
-```bash
-export SIGHTENGINE_API_USER=your_api_user
-export SIGHTENGINE_API_SECRET=your_api_secret
-npx @solid/community-server -c config-with-moderation.json
-```
-
-## For Local Development/Testing
-
-When testing the plugin locally (before publishing):
-
-1. Use `npm link` to link the local plugin
-2. Use the `config-with-moderation.json` file in the plugin directory
-3. Run CSS pointing to that config file
-
-## Key Difference
-
-- **Production**: Import `@solid/moderation-plugin:config/default.json` (from npm package)
-- **Local Testing**: Use full path to `config-with-moderation.json` (from source directory)

package/DEVELOPMENT.md

@@ -1,129 +0,0 @@
-# Development Notes
-
-## Components.js Module Loading Issue
-
-### Problem
-Components.js cannot load modules via `npm link` due to symlink resolution issues. When using `npm link`, the plugin appears in `node_modules/@solid/moderation-plugin` as a symlink, but Components.js's module loader cannot follow it to instantiate classes.
-
-### Symptoms
-- Server starts without errors
-- Config file is loaded successfully
-- No moderation logs appear when uploading files
-- ModerationOperationHandler is never instantiated
-- Uploads succeed without any moderation checks
-
-### Root Cause
-Components.js uses its own module resolution that doesn't properly handle symlinked packages. The `requireElement` in the generated `.jsonld` files points to the class name, but Components.js cannot resolve the actual module path through the symlink.
-
-### Solutions
-
-#### Option 1: File Path Dependency (Recommended for Development)
-Add to CSS's `package.json`:
-```json
-{
-  "dependencies": {
-    "@solid/moderation-plugin": "file:../solid-moderation"
-  }
-}
-```
-
-Then run:
-```bash
-cd /Users/opendata/CommunitySolidServer
-npm install
-```
-
-This creates a proper copy (not symlink) in node_modules.
-
-**After code changes:**
-```bash
-cd /Users/opendata/solid-moderation
-npm run build
-cd /Users/opendata/CommunitySolidServer
-npm install  # Re-copies the updated files
-```
-
-#### Option 2: Publish to npm (Recommended for Production)
-```bash
-cd /Users/opendata/solid-moderation
-npm publish
-```
-
-Then in CSS:
-```bash
-npm install @solid/moderation-plugin@latest
-```
-
-#### Option 3: Manual Copy (Quick Testing Only)
-```bash
-rm -rf /Users/opendata/CommunitySolidServer/node_modules/@solid/moderation-plugin
-cp -r /Users/opendata/solid-moderation /Users/opendata/CommunitySolidServer/node_modules/@solid/moderation-plugin
-```
-
-**Note:** Must repeat after every code change.
-
-## Current Configuration
-
-### Environment Variables
-```bash
-export SIGHTENGINE_API_USER="1060049443"
-export SIGHTENGINE_API_SECRET="QRQ8HUmh4hyvhZjksBJq5ZaNYPLPEKXu"
-```
-
-### Thresholds (Configurable in config-with-moderation.json)
-- **Image Nudity**: 0.1 (10% - very strict)
-- **Text Sexual**: 0.1 (10% - very strict)
-- **Text Toxic**: 0.1 (10% - very strict)
-- **Video Nudity**: 0.1 (10% - very strict)
-
-Lower values = stricter moderation (blocks more content)
-Higher values = lenient moderation (blocks less content)
-Range: 0.0 (block everything) to 1.0 (block nothing)
-
-### Starting the Server
-```bash
-cd /Users/opendata/CommunitySolidServer
-export SIGHTENGINE_API_USER="1060049443"
-export SIGHTENGINE_API_SECRET="QRQ8HUmh4hyvhZjksBJq5ZaNYPLPEKXu"
-npm start -- -c /Users/opendata/solid-moderation/config-with-moderation.json -f data/ -p 3009 -l debug > logs/server.log 2>&1 &
-```
-
-### Checking Logs
-```bash
-# Watch for moderation activity
-tail -f logs/server.log | grep -i moderation
-
-# Check if handler is invoked
-grep "MODERATION: Checking" logs/server.log
-
-# Check for API failures
-grep "MODERATION:.*failed" logs/server.log
-```
-
-## Features Implemented
-
-### Code Structure
-- **ModerationOperationHandler**: Wraps POST/PUT/PATCH handlers
-- **ModerationMixin**: Performs actual content checks
-- **ModerationStore**: Audit logging for violations
-- **SightEngineProvider**: API client for SightEngine
-- **Configurable thresholds**: All thresholds adjustable via config
-
-### Moderation Checks
-- **Images**: Nudity detection
-- **Text**: Sexual content and toxic language
-- **Video**: Nudity detection
-- **Fail-open policy**: Allows content if API fails
-
-### Debug Logging
-- Handler invocation logs
-- Content type detection logs
-- API response with scores
-- Threshold comparison logs
-- Failure reason logs
-
-## Known Issues
-
-1. **npm link doesn't work** - Use file path dependency instead
-2. **Environment variables** - Must be set before starting server
-3. **Audit logs** - Only record violations, not all checks

package/ENV-VARIABLES.md

@@ -1,137 +0,0 @@
-# Environment Variables Explained
-
-## What `export` Does
-
-```bash
-export SIGHTENGINE_API_USER=your_api_user
-export SIGHTENGINE_API_SECRET=your_api_secret
-```
-
-These commands set **environment variables** in your shell session:
-
-- `export` makes the variable available to all programs you run in that terminal
-- `SIGHTENGINE_API_USER` is the variable name
-- `your_api_user` is the value (replace with your actual API credentials)
-
-## How the Plugin Uses These Variables
-
-In `config/default.json`, you'll see:
-
-```json
-"ModerationConfig:_sightEngine": {
-  "ModerationConfig:_sightEngine_apiUser": "${SIGHTENGINE_API_USER}",
-  "ModerationConfig:_sightEngine_apiSecret": "${SIGHTENGINE_API_SECRET}"
-}
-```
-
-The `${SIGHTENGINE_API_USER}` syntax means:
-- "Look for an environment variable named SIGHTENGINE_API_USER"
-- "Replace this placeholder with its value"
-
-## Example Flow
-
-1. **You set the variables:**
-   ```bash
-   export SIGHTENGINE_API_USER=abc123
-   export SIGHTENGINE_API_SECRET=xyz789
-   ```
-
-2. **You start CSS:**
-   ```bash
-   npx @solid/community-server -c config.json
-   ```
-
-3. **The plugin reads the config and replaces placeholders:**
-   - `${SIGHTENGINE_API_USER}` becomes `abc123`
-   - `${SIGHTENGINE_API_SECRET}` becomes `xyz789`
-
-4. **The plugin uses these credentials to call SightEngine API**
-
-## Why Use Environment Variables?
-
-✅ **Security**: Credentials aren't stored in config files (which might be committed to git)
-✅ **Flexibility**: Different credentials for dev/staging/production without changing code
-✅ **Standard Practice**: Common pattern for managing secrets
-
-## Alternative Methods
-
-### Option 1: Set per command (temporary)
-```bash
-SIGHTENGINE_API_USER=abc123 SIGHTENGINE_API_SECRET=xyz789 npx @solid/community-server -c config.json
-```
-
-### Option 2: Use a .env file (with dotenv)
-Create `.env` file:
-```
-SIGHTENGINE_API_USER=abc123
-SIGHTENGINE_API_SECRET=xyz789
-```
-
-### Option 3: Set in shell profile (permanent) ⭐ RECOMMENDED FOR PRODUCTION
-Add to `~/.bashrc` or `~/.zshrc`:
-```bash
-export SIGHTENGINE_API_USER=abc123
-export SIGHTENGINE_API_SECRET=xyz789
-```
-
-### Option 4: System service environment file (for systemd)
-Create `/etc/systemd/system/solid-server.service.d/override.conf`:
-```ini
-[Service]
-Environment="SIGHTENGINE_API_USER=abc123"
-Environment="SIGHTENGINE_API_SECRET=xyz789"
-```
-
-## What Happens on Server Restart?
-
-### ❌ If you only used `export` in terminal:
-- Variables are **LOST** when terminal closes or server restarts
-- Server will fail to moderate content (falls back to fail-open policy)
-- You must re-export before starting server again
-
-### ✅ If you added to shell profile (`~/.bashrc` or `~/.zshrc`):
-- Variables are **PRESERVED** across terminal sessions
-- But still lost on full system reboot unless server auto-starts with those variables
-
-### ✅ If you use systemd service file:
-- Variables are **ALWAYS AVAILABLE** to the service
-- Survives server restarts and system reboots
-- **BEST for production servers**
-
-### ✅ If you use Docker:
-```yaml
-services:
-  solid-server:
-    environment:
-      - SIGHTENGINE_API_USER=abc123
-      - SIGHTENGINE_API_SECRET=xyz789
-```
-Variables are preserved in container configuration.
-
-## Production Recommendation
-
-For a production server that needs to survive restarts:
-
-1. **Use systemd service** with environment variables in service file
-2. **Or use Docker** with environment variables in docker-compose.yml
-3. **Or use a process manager** like PM2 with ecosystem.config.js:
-   ```javascript
-   module.exports = {
-     apps: [{
-       name: 'solid-server',
-       script: 'npx',
-       args: '@solid/community-server -c config.json',
-       env: {
-         SIGHTENGINE_API_USER: 'abc123',
-         SIGHTENGINE_API_SECRET: 'xyz789'
-       }
-     }]
-   }
-   ```
-
-## Getting Your API Credentials
-
-1. Sign up at https://sightengine.com/
-2. Go to your dashboard
-3. Find your API User and API Secret
-4. Replace `your_api_user` and `your_api_secret` with those values

package/INSTALLATION.md

@@ -1,90 +0,0 @@
-# Files Generated in Community Solid Server
-
-When you install `@solid/moderation-plugin` in your Community Solid Server, the following files will be generated in `node_modules/@solid/moderation-plugin/`:
-
-## Directory Structure
-
-```
-node_modules/@solid/moderation-plugin/
-├── dist/                           # Compiled JavaScript and metadata
-│   ├── components/                 # Components.js metadata
-│   │   ├── components.jsonld       # Component definitions
-│   │   └── context.jsonld          # JSON-LD context
-│   │
-│   ├── providers/                  # API providers
-│   │   ├── SightEngineProvider.js
-│   │   ├── SightEngineProvider.d.ts
-│   │   ├── SightEngineProvider.js.map
-│   │   ├── SightEngineProvider.d.ts.map
-│   │   └── SightEngineProvider.jsonld
-│   │
-│   ├── util/                       # Utilities
-│   │   ├── GuardedStream.js
-│   │   ├── GuardedStream.d.ts
-│   │   └── *.map files
-│   │
-│   ├── index.js                    # Main entry point
-│   ├── index.d.ts                  # TypeScript definitions
-│   ├── ModerationOperationHandler.js
-│   ├── ModerationOperationHandler.d.ts
-│   ├── ModerationOperationHandler.jsonld
-│   ├── ModerationConfig.js
-│   ├── ModerationConfig.d.ts
-│   ├── ModerationConfig.jsonld
-│   ├── ModerationStore.js
-│   ├── ModerationStore.d.ts
-│   ├── ModerationStore.jsonld
-│   ├── ModerationMixin.js
-│   ├── ModerationMixin.d.ts
-│   ├── ModerationMixin.jsonld
-│   ├── ModerationRecord.js
-│   ├── ModerationRecord.d.ts
-│   ├── ModerationRecord.jsonld
-│   └── *.map files                 # Source maps
-│
-├── config/                         # Configuration templates
-│   └── default.json                # Default moderation settings
-│
-├── package.json                    # Package metadata
-├── README.md                       # Documentation
-└── LICENSE                         # MIT License
-```
-
-## Runtime Files (Created During Operation)
-
-When CSS runs with moderation enabled, these files/folders are created:
-
-```
-your-css-project/
-├── data/
-│   └── moderation-logs/            # Audit logs (if enabled)
-│       ├── 2024-01-20.jsonl        # Daily log files
-│       ├── 2024-01-21.jsonl
-│       └── ...
-│
-└── /tmp/                           # Temporary files during analysis
-    └── moderation_*.jpg/mp4        # Auto-deleted after analysis
-```
-
-## Key Files Explained
-
-### Components.js Files (*.jsonld)
-- Used by CSS's dependency injection system
-- Define how classes are instantiated and wired together
-- Allow configuration through JSON-LD config files
-
-### JavaScript Files (*.js)
-- Compiled TypeScript code
-- Main application logic
-
-### TypeScript Definitions (*.d.ts)
-- Type information for TypeScript users
-- Enable IDE autocomplete and type checking
-
-### Source Maps (*.map)
-- Map compiled JS back to original TypeScript
-- Used for debugging
-
-### config/default.json
-- Template configuration with default thresholds
-- Can be imported in CSS config files