### Import Migration Example for @cloudcreate/core

Source: https://github.com/cloudcreate-ai/cloudcreate-lib/blob/main/README.md

Shows the change in import paths when migrating from the old package name to the new one.

```javascript
// before
import { minifyAggressive } from '@cloudcreate/cloudcreate-core/css';

// after
import { minifyAggressive } from '@cloudcreate/core/css';
```

--------------------------------

### Smoke Import Test

Source: https://github.com/cloudcreate-ai/cloudcreate-lib/blob/main/RELEASE.md

Test the installability and basic functionality of the published package by performing a smoke import test. This command executes a Node.js script that imports a module and logs a boolean value.

```bash
node --input-type=module -e "import { browser } from '@cloudcreate/core'; console.log(Boolean(browser));"
```

--------------------------------

### Normalize and Get Browser Tool Metadata

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Use `normalizeBrowserTool` to resolve tool aliases to canonical IDs and `getBrowserTool` to retrieve metadata for browser tools. Returns `null` for unknown tools.

```javascript
import { browser } from '@cloudcreate/core';

// Normalize aliases to canonical IDs
console.log(browser.normalizeBrowserTool('minify'));    // → "css:minify"
console.log(browser.normalizeBrowserTool('md'));        // → "markdown:html"
console.log(browser.normalizeBrowserTool('favicon'));   // → "image:favicon"

// Get tool metadata
const tool = browser.getBrowserTool('archive:decompress');
console.log(tool);  // → { id: "archive:decompress", path: "/archive/decompress" }

console.log(browser.getBrowserTool('unknown')); // → null
```

--------------------------------

### CSS Minification and Archiving with @cloudcreate/core

Source: https://github.com/cloudcreate-ai/cloudcreate-lib/blob/main/README.md

Demonstrates using the CSS minification utility and then archiving the result using the archive module. Ensure the necessary modules are imported.

```javascript
import { minifyAggressive } from '@cloudcreate/core/css';
import { archive } from '@cloudcreate/core';

const css = minifyAggressive('.demo { color: red; }');
const zipBytes = await archive.compressZipBytes([
  { name: 'style.css', data: new TextEncoder().encode(css) },
]);
```

--------------------------------

### `compressTarGzBytes(files)` / `compressTarGz(files)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Bundles multiple file entries into a POSIX TAR archive and then GZIP-compresses it. The underlying TAR writer sets standard Unix permissions (0644).

```APIDOC
## `compressTarGzBytes(files)` / `compressTarGz(files)`

### Description
Bundles multiple file entries into a POSIX TAR archive then GZIP-compresses it. The underlying TAR writer sets standard Unix permissions (0644).

### Parameters
- `files` (Array<Object>) - An array of file objects, where each object has `name` (string) and `data` (Uint8Array) properties.

### Example
```js
import { archive } from '@cloudcreate/core';
import { writeFileSync } from 'fs';

const enc = new TextEncoder();
const tarGzBytes = await archive.compressTarGzBytes([
  { name: 'src/index.js', data: enc.encode('export default 42;') },
  { name: 'src/util.js', data: enc.encode('export const noop = () => {};') },
]);

// Write to disk in Node.js
writeFileSync('bundle.tar.gz', tarGzBytes);
```
```

--------------------------------

### List Available Browser Tools

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Iterates through all available browser tool definitions and logs their IDs and paths. Useful for discovering available functionalities.

```javascript
import { browser } from '@cloudcreate/core';

browser.BROWSER_TOOLS.forEach(({ id, path }) => {
  console.log(`${id.padEnd(22)} → ${path}`);
});
// css:minify             → /css/minify
// css:beautify           → /css/beautify
// markdown:html          → /markdown
// table:convert          → /table
// archive:compress       → /archive/compress
// archive:decompress     → /archive/decompress
// image:compress         → /image/compress
// image:convert          → /image/convert
// image:resize           → /image/resize
// image:crop             → /image/crop
// image:rotate           → /image/rotate
// image:preview          → /image/preview
// image:favicon          → /image/favicon
// image:batch            → /image/batch
// image:gif              → /image/gif
// image:appstore         → /image/appstore
// image:playstore        → /image/playstore
// pdf:view               → /pdf
// pdf:compress           → /pdf/compress
// workflow               → /workflow
// workflow:advanced      → /workflow/advanced
```

--------------------------------

### buildCloudCreateToolUrl(tool, options?)

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Generates a complete URL for CloudCreate.ai browser tools, allowing for custom origins, locale prefixes, and typed query parameters.

```APIDOC
## buildCloudCreateToolUrl(tool, options?)

### Description
Build a CloudCreate.ai tool URL. Generates a fully-qualified URL for any CloudCreate.ai browser tool with typed query parameters. Supports custom origins, locale prefixes, and pre-built `URLSearchParams`.

### Parameters
- **tool** (string) - The identifier of the tool (e.g., 'css:minify').
- **options** (object, optional) - Configuration options for the URL, such as `origin`, `locale`, and tool-specific parameters.

### Request Example
```js
import { browser } from '@cloudcreate/core';

// Basic tool URL
const url = browser.buildCloudCreateToolUrl('css:minify');
console.log(url);
// → "https://cloudcreate.ai/css/minify"

// With options
const minifyUrl = browser.buildCloudCreateToolUrl('css:minify', { level: 'aggressive' });
console.log(minifyUrl);
// → "https://cloudcreate.ai/css/minify?level=aggressive"

// Image resize with quality and format
const resizeUrl = browser.buildCloudCreateToolUrl('image:resize', {
  mode: 'width',
  width: 800,
  quality: 85,
  format: 'webp',
});
console.log(resizeUrl);
// → "https://cloudcreate.ai/image/resize?mode=width&tw=800&q=85&f=webp"

// With locale and custom origin
const localUrl = browser.buildCloudCreateToolUrl('table:convert', {
  origin: 'http://localhost:5173',
  locale: 'fr',
  format: 'json',
});
console.log(localUrl);
// → "http://localhost:5173/fr/table?fmt=json"

// Unknown tool throws
try {
  browser.buildCloudCreateToolUrl('nonexistent');
} catch (e) {
  console.error(e.message);
  // → "Unknown CloudCreate browser tool: nonexistent"
}
```
```

--------------------------------

### `parseTarEntries(buffer)` / `createTarBytes(files)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Provides low-level TAR I/O capabilities. `parseTarEntries` parses raw TAR bytes into file entries, while `createTarBytes` builds a TAR archive from scratch without GZIP compression.

```APIDOC
## `parseTarEntries(buffer)` / `createTarBytes(files)`

### Description
Parse raw TAR bytes into file entries or build a TAR archive from scratch without GZIP compression.

### Parameters
- `buffer` (Uint8Array | Buffer) - For `parseTarEntries`, the buffer containing TAR data.
- `files` (Array<Object>) - For `createTarBytes`, an array of file objects with `name` and `data` properties.

### Returns
- `Array<{ name: string, size: number, data: Uint8Array }>` (for `parseTarEntries`)
- `Uint8Array` (for `createTarBytes`)

### Example
```js
import { archive } from '@cloudcreate/core';

// Build a raw TAR
const enc = new TextEncoder();
const tarBytes = archive.createTarBytes([
  { name: 'a.txt', data: enc.encode('file A') },
  { name: 'b.txt', data: enc.encode('file B') },
]);

// Round-trip: parse it back
const entries = archive.parseTarEntries(tarBytes);
console.log(entries.map(e => e.name)); // → ["a.txt", "b.txt"]
```
```

--------------------------------

### Create TAR.GZ Archive Bytes

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Bundles multiple file entries into a POSIX TAR archive then GZIP-compresses it. The underlying TAR writer sets standard Unix permissions (0644). Use `compressTarGzBytes` for Node.js and `compressTarGz` for browser environments.

```javascript
import { archive } from '@cloudcreate/core';

const enc = new TextEncoder();
const tarGzBytes = await archive.compressTarGzBytes([
  { name: 'src/index.js', data: enc.encode('export default 42;') },
  { name: 'src/util.js', data: enc.encode('export const noop = () => {};') },
]);

// Write to disk in Node.js
import { writeFileSync } from 'fs';
writeFileSync('bundle.tar.gz', tarGzBytes);
```

--------------------------------

### Build Tool Query Parameters

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Constructs URLSearchParams for a given tool and options. Useful for manual URL construction or integration with other routing libraries. Ensure correct tool names and option keys are used.

```javascript
import { browser } from '@cloudcreate/core';

const params = browser.buildToolQuery('image:crop', {
  preset: '16:9',
  quality: 90,
  format: 'jpeg',
});

console.log(params.toString());
// → "preset=16%3A9&q=90&f=jpeg"
```

```javascript
// Image rotate with flip
const rotateParams = browser.buildToolQuery('image:rotate', {
  rotate: 90,
  flipH: true,
  format: 'png',
});
console.log(rotateParams.toString());
// → "r=90&fh=1&f=png"
```

--------------------------------

### Basic CSS Minification with @cloudcreate/core/css

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Strips comments and collapses whitespace for a lightweight CSS minification. Handles non-string input by returning an empty string.

```javascript
import { minifyBasic } from '@cloudcreate/core/css';

const input = "
  /* Reset styles */
  body {
    margin:  0;
    padding:  0;
  }
";

const result = minifyBasic(input);
console.log(result);
// → "body { margin: 0; padding: 0; }"

// Non-string input returns empty string gracefully
console.log(minifyBasic(null)); // → ""
```

--------------------------------

### Build CloudCreate.ai Tool URLs

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Use `buildCloudCreateToolUrl` to construct valid URLs for CloudCreate.ai browser tools. Supports custom origins, locale prefixes, and query parameters.

```javascript
import { browser } from '@cloudcreate/core';

// Basic tool URL
const url = browser.buildCloudCreateToolUrl('css:minify');
console.log(url);
// → "https://cloudcreate.ai/css/minify"

// With options
const minifyUrl = browser.buildCloudCreateToolUrl('css:minify', { level: 'aggressive' });
console.log(minifyUrl);
// → "https://cloudcreate.ai/css/minify?level=aggressive"

// Image resize with quality and format
const resizeUrl = browser.buildCloudCreateToolUrl('image:resize', {
  mode: 'width',
  width: 800,
  quality: 85,
  format: 'webp',
});
console.log(resizeUrl);
// → "https://cloudcreate.ai/image/resize?mode=width&tw=800&q=85&f=webp"

// With locale and custom origin
const localUrl = browser.buildCloudCreateToolUrl('table:convert', {
  origin: 'http://localhost:5173',
  locale: 'fr',
  format: 'json',
});
console.log(localUrl);
// → "http://localhost:5173/fr/table?fmt=json"

// Unknown tool throws
try {
  browser.buildCloudCreateToolUrl('nonexistent');
} catch (e) {
  console.error(e.message);
  // → "Unknown CloudCreate browser tool: nonexistent"
}
```

--------------------------------

### BROWSER_TOOLS

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Lists all available tool definitions that can be used with the browser module. Each tool has a unique ID and a corresponding path.

```APIDOC
## `BROWSER_TOOLS` — Full list of available tool definitions

This constant provides a list of all available tools within the browser module. Each tool definition includes an `id` and a `path`.

### Example Usage
```js
import { browser } from '@cloudcreate/core';

browser.BROWSER_TOOLS.forEach(({ id, path }) => {
  console.log(`${id.padEnd(22)} → ${path}`);
});
```

### Available Tools:
- `css:minify` → `/css/minify`
- `css:beautify` → `/css/beautify`
- `markdown:html` → `/markdown`
- `table:convert` → `/table`
- `archive:compress` → `/archive/compress`
- `archive:decompress` → `/archive/decompress`
- `image:compress` → `/image/compress`
- `image:convert` → `/image/convert`
- `image:resize` → `/image/resize`
- `image:crop` → `/image/crop`
- `image:rotate` → `/image/rotate`
- `image:preview` → `/image/preview`
- `image:favicon` → `/image/favicon`
- `image:batch` → `/image/batch`
- `image:gif` → `/image/gif`
- `image:appstore` → `/image/appstore`
- `image:playstore` → `/image/playstore`
- `pdf:view` → `/pdf`
- `pdf:compress` → `/pdf/compress`
- `workflow` → `/workflow`
- `workflow:advanced` → `/workflow/advanced`
```

--------------------------------

### `decompressTarGzEntries(buffer)` / `decompressTarGz(buffer)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Decompresses a GZIP-compressed TAR archive. It walks the TAR header blocks and returns a flat array of file entries, skipping directories.

```APIDOC
## `decompressTarGzEntries(buffer)` / `decompressTarGz(buffer)`

### Description
Decompresses GZIP then walks the TAR header blocks, returning a flat array of file entries (directories are skipped).

### Parameters
- `buffer` (Uint8Array | Buffer) - The buffer containing the TAR.GZ archive data.

### Returns
- `Array<{ name: string, size: number, data: Uint8Array }> `

### Example
```js
import { archive } from '@cloudcreate/core';
import { readFileSync } from 'fs';

const buffer = readFileSync('bundle.tar.gz');
const entries = archive.decompressTarGzEntries(buffer);

entries.forEach(({ name, size, data }) => {
  console.log(`${name} (${size} bytes)`);
  // → src/index.js (18 bytes)
  // → src/util.js (29 bytes)
});
```
```

--------------------------------

### `formatFileSize(bytes)` / `formatLabelFromFilename(filename)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Utility functions for formatting file sizes into human-readable strings and generating display labels from filenames.

```APIDOC
## `formatFileSize(bytes)` / `formatLabelFromFilename(filename)` — Display helpers

### Description
Utility functions for formatting file sizes into human-readable strings and generating display labels from filenames.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { image } from '@cloudcreate/core';

console.log(image.formatFileSize(512));          // → "512 B"
console.log(image.formatFileSize(2048));         // → "2.0 KB"
console.log(image.formatFileSize(3145728));      // → "3.00 MB"

console.log(image.formatLabelFromFilename('photo.jpg'));   // → "JPEG"
console.log(image.formatLabelFromFilename('icon.webp'));   // → "WEBP"
console.log(image.formatLabelFromFilename('doc.pdf'));     // → "PDF"
```

### Response
#### Success Response (200)
- **formattedString** (string) - The formatted file size or label.

#### Response Example
```json
{
  "formattedString": "3.00 MB"
}
```
```

--------------------------------

### File Size and Label Formatting

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Utility functions for displaying file sizes in human-readable formats (e.g., KB, MB) and generating display labels from filenames, normalizing extensions.

```javascript
import { image } from '@cloudcreate/core';

console.log(image.formatFileSize(512));          // → "512 B"
console.log(image.formatFileSize(2048));         // → "2.0 KB"
console.log(image.formatFileSize(3145728));      // → "3.00 MB"

console.log(image.formatLabelFromFilename('photo.jpg'));   // → "JPEG"
console.log(image.formatLabelFromFilename('icon.webp'));   // → "WEBP"
console.log(image.formatLabelFromFilename('doc.pdf'));     // → "PDF"
```

--------------------------------

### `compressImageBytes(buffer, options?)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Compresses raw image bytes for CLI/server use. Takes an ArrayBuffer or Uint8Array plus explicit format hints.

```APIDOC
## `compressImageBytes(buffer, options?)` — Compress raw image bytes (Node.js / browser)

### Description
Byte-oriented equivalent for CLI/server use. Takes an `ArrayBuffer` or `Uint8Array` plus explicit format hints.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **buffer** (ArrayBuffer | Uint8Array) - The raw image bytes.
- **options** (object) - Optional compression settings.
  - **sourceFormat** (string) - The format of the input image (e.g., 'png', 'jpeg').
  - **targetFormat** (string) - The desired output format (e.g., 'avif', 'webp').
  - **quality** (number) - The compression quality (0-100).

### Request Example
```javascript
import { image } from '@cloudcreate/core';
import { readFileSync, writeFileSync } from 'fs';

const input = readFileSync('photo.png');

const { buffer, mime, ext, width, height } = await image.compressImageBytes(input, {
  sourceFormat: 'png',
  targetFormat: 'avif',
  quality: 70,
});

writeFileSync(`photo.${ext}`, Buffer.from(buffer));
console.log(`Saved as ${ext} (${mime}), ${width}×${height}`);
// → Saved as avif (image/avif), 1920×1080
```

### Response
#### Success Response (200)
- **buffer** (ArrayBuffer) - The compressed image bytes.
- **mime** (string) - The MIME type of the compressed image.
- **ext** (string) - The file extension for the compressed image.
- **width** (number) - The width of the image in pixels.
- **height** (number) - The height of the image in pixels.

#### Response Example
```json
{
  "buffer": "ArrayBuffer object",
  "mime": "image/avif",
  "ext": "avif",
  "width": 1920,
  "height": 1080
}
```
```

--------------------------------

### Aggressive CSS Minification with @cloudcreate/core/css

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Performs full structural CSS minification using the CSSO optimizer. Throws an error on malformed input.

```javascript
import { minifyAggressive } from '@cloudcreate/core/css';

const input = "
  .button { color: red; }
  .button { background: blue; font-size: 14px; }
";

try {
  const result = minifyAggressive(input);
  console.log(result);
  // → ".button{color:red;background:#00f;font-size:14px}"
} catch (e) {
  console.error('Minification failed:', e.message);
}
```

--------------------------------

### Publish Package

Source: https://github.com/cloudcreate-ai/cloudcreate-lib/blob/main/RELEASE.md

Publish the package to the npm registry with public access. Ensure you have committed version and document updates before running this command.

```bash
npm publish --access public
```

--------------------------------

### `compressGzipBytes(file, filename?)` / `compressGzip(file, filename?)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Compresses a single file-like entry to GZIP format. The original filename is stored in the GZIP header if provided. The `compressGzipBytes` function returns a Uint8Array, while `compressGzip` in the browser returns a Blob.

```APIDOC
## `compressGzipBytes(file, filename?)` / `compressGzip(file, filename?)`

### Description
Compresses one file-like entry to GZIP format. Stores the original filename in the GZIP header when provided.

### Method
`compressGzipBytes` returns `Uint8Array`.
`compressGzip` (browser) returns `Blob` with type `application/gzip`.

### Example
```js
import { archive } from '@cloudcreate/core';

const data = new TextEncoder().encode('Large text content to compress...');

// Node.js or general usage
const gzBytes = await archive.compressGzipBytes(data, 'output.txt');
console.log(gzBytes instanceof Uint8Array); // → true

// Browser usage
const blob = await archive.compressGzip(data, 'output.txt');
```
```

--------------------------------

### `compressImageFile(file, options?)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Compresses or converts a browser File object. Reads a File, decodes it, re-encodes it at the requested quality/format, and returns a result with a download-ready Blob.

```APIDOC
## `compressImageFile(file, options?)` — Compress or convert a browser File

### Description
High-level helper for the browser. Reads a `File` object, decodes it, re-encodes at the requested quality/format, and returns a result with a download-ready `Blob`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { image } from '@cloudcreate/core';

// file: a File object from <input type="file">
const result = await image.compressImageFile(file, {
  quality: 80,
  targetFormat: 'webp',
});

console.log(result.outputName);  // → "photo.webp"
console.log(result.newSize);     // → 45231 (bytes)
console.log(result.ratio);       // → 42.1 (% reduction)
console.log(result.width);       // → 1920
console.log(result.height);      // → 1080

// Trigger browser download
const url = URL.createObjectURL(result.blob);
const a = document.createElement('a');
a.href = url; a.download = result.outputName; a.click();
```

### Response
#### Success Response (200)
- **blob** (Blob) - The compressed image data.
- **outputName** (string) - The suggested filename for the output image.
- **newSize** (number) - The size of the new image in bytes.
- **ratio** (number) - The percentage reduction in file size.
- **width** (number) - The width of the image in pixels.
- **height** (number) - The height of the image in pixels.

#### Response Example
```json
{
  "outputName": "photo.webp",
  "newSize": 45231,
  "ratio": 42.1,
  "width": 1920,
  "height": 1080,
  "blob": "Blob object"
}
```
```

--------------------------------

### Low-level TAR I/O

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Parse raw TAR bytes into file entries or build a TAR archive from scratch without GZIP compression. Use `parseTarEntries` to read and `createTarBytes` to write.

```javascript
import { archive } from '@cloudcreate/core';

// Build a raw TAR
const enc = new TextEncoder();
const tarBytes = archive.createTarBytes([
  { name: 'a.txt', data: enc.encode('file A') },
  { name: 'b.txt', data: enc.encode('file B') },
]);

// Round-trip: parse it back
const entries = archive.parseTarEntries(tarBytes);
console.log(entries.map(e => e.name)); // → ["a.txt", "b.txt"]
```

--------------------------------

### Compress Browser Image File

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Use this helper for browser-based image compression and conversion. It takes a File object and returns a Blob ready for download, along with metadata about the transformation.

```javascript
import { image } from '@cloudcreate/core';

// file: a File object from <input type="file">
const result = await image.compressImageFile(file, {
  quality: 80,
  targetFormat: 'webp',
});

console.log(result.outputName);  // → "photo.webp"
console.log(result.newSize);     // → 45231 (bytes)
console.log(result.ratio);       // → 42.1 (% reduction)
console.log(result.width);       // → 1920
console.log(result.height);      // → 1080

// Trigger browser download
const url = URL.createObjectURL(result.blob);
const a = document.createElement('a');
a.href = url; a.download = result.outputName; a.click();
```

--------------------------------

### Beautify CSS with @cloudcreate/core/css

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Formats minified or unstructured CSS into a human-readable form with 2-space indentation. Returns an empty string for non-string inputs.

```javascript
import { beautify } from '@cloudcreate/core/css';

const minified = '.nav{display:flex;gap:8px}.nav a{color:#333;text-decoration:none}';

try {
  const pretty = beautify(minified);
  console.log(pretty);
  // → .nav {
  //     display: flex;
  //     gap: 8px;
  //   }
  //   .nav a {
  //     color: #333;
  //     text-decoration: none;
  //   }
} catch (e) {
  console.error('Beautify failed:', e.message);
}
```

--------------------------------

### `detectFormat(filename)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Infers the archive format from a given filename. It correctly handles double extensions like `.tar.gz` and `.tgz`. Returns the format string ('zip', 'gzip', 'targz', 'brotli') or `null` if the format cannot be determined.

```APIDOC
## `detectFormat(filename)`

### Description
Returns `'zip'`, `'gzip'`, `'targz'`, `'brotli'`, or `null`. Handles double-extension `.tar.gz` and `.tgz` correctly.

### Parameters
- `filename` (string) - The name of the file to detect the format from.

### Returns
- `string | null` - The detected archive format or null.

### Example
```js
import { archive } from '@cloudcreate/core';

console.log(archive.detectFormat('assets.zip'));        // → "zip"
console.log(archive.detectFormat('logs.tar.gz'));       // → "targz"
console.log(archive.detectFormat('bundle.tgz'));        // → "targz"
console.log(archive.detectFormat('data.br'));           // → "brotli"
console.log(archive.detectFormat('image.png'));         // → null
```
```

--------------------------------

### buildToolQuery

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Constructs URLSearchParams for a given tool and options, excluding the base URL. This is useful for manual URL construction or integration with other routing libraries.

```APIDOC
## `buildToolQuery(tool, options)` — Build only the URLSearchParams for a tool

This function generates a `URLSearchParams` instance for a specified tool and its associated options. It does not include the base URL, making it flexible for various integration scenarios.

### Parameters
- **tool** (string) - Required - The identifier of the tool (e.g., 'image:crop').
- **options** (object) - Required - An object containing key-value pairs for the tool's parameters.

### Returns
- `URLSearchParams` - An instance of URLSearchParams containing the tool's query parameters.

### Example Usage:

#### Image Crop:
```js
import { browser } from '@cloudcreate/core';

const params = browser.buildToolQuery('image:crop', {
  preset: '16:9',
  quality: 90,
  format: 'jpeg',
});

console.log(params.toString());
// Expected output: "preset=16%3A9&q=90&f=jpeg"
```

#### Image Rotate with Flip:
```js
import { browser } from '@cloudcreate/core';

const rotateParams = browser.buildToolQuery('image:rotate', {
  rotate: 90,
  flipH: true,
  format: 'png',
});

console.log(rotateParams.toString());
// Expected output: "r=90&fh=1&f=png"
```
```

--------------------------------

### Infer Archive Format from Filename

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Returns 'zip', 'gzip', 'targz', 'brotli', or null. Handles double-extension `.tar.gz` and `.tgz` correctly. This function is synchronous.

```javascript
import { archive } from '@cloudcreate/core';

console.log(archive.detectFormat('assets.zip'));        // → "zip"
console.log(archive.detectFormat('logs.tar.gz'));       // → "targz"
console.log(archive.detectFormat('bundle.tgz'));        // → "targz"
console.log(archive.detectFormat('data.br'));           // → "brotli"
console.log(archive.detectFormat('image.png'));         // → null
```

--------------------------------

### Create ZIP Archive with @cloudcreate/core/archive

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Creates a ZIP archive from an array of file-like objects. Provides both a byte array (`compressZipBytes`) and a Blob (`compressZip`) output, suitable for Node.js and browser environments respectively.

```javascript
import { archive } from '@cloudcreate/core';

const enc = new TextEncoder();
const files = [
  { name: 'hello.txt', data: enc.encode('Hello, world!') },
  { name: 'config.json', data: enc.encode(JSON.stringify({ version: 1 })) },
];

// Bytes API (Node.js / browser)
const zipBytes = await archive.compressZipBytes(files);
console.log(zipBytes instanceof Uint8Array); // → true
console.log(zipBytes.length); // → e.g. 342

// Blob API (browser download)
const blob = await archive.compressZip(files);
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url; a.download = 'bundle.zip'; a.click();
```

--------------------------------

### Archive Module Functions

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Provides functions to compress files into ZIP archives, returning either bytes or a Blob.

```APIDOC
## compressZipBytes(files) / compressZip(files)

### Description

Creates a ZIP archive from an array of file-like entries. `compressZipBytes` returns a `Uint8Array`, while `compressZip` returns a `Blob` suitable for browser downloads.

### Method

`compressZipBytes` (returns `Uint8Array`)
`compressZip` (returns `Blob`)

### Parameters

- **files** (Array<object>) - An array of file-like entries. Each entry should be an object with:
  - **name** (string) - The name of the file within the archive.
  - **data** (Uint8Array | ArrayBuffer | Blob | File) - The content of the file.

### Returns

- `compressZipBytes`: `Uint8Array` - The ZIP archive as a byte array.
- `compressZip`: `Blob` - The ZIP archive as a Blob object.

### Example

```js
import { archive } from '@cloudcreate/core';

const enc = new TextEncoder();
const files = [
  { name: 'hello.txt', data: enc.encode('Hello, world!') },
  { name: 'config.json', data: enc.encode(JSON.stringify({ version: 1 })) },
];

// Bytes API (Node.js / browser)
const zipBytes = await archive.compressZipBytes(files);
console.log(zipBytes instanceof Uint8Array); // → true
console.log(zipBytes.length); // → e.g. 342

// Blob API (browser download)
const blob = await archive.compressZip(files);
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url; a.download = 'bundle.zip'; a.click();
```
```

--------------------------------

### Markdown to HTML Rendering with @cloudcreate/core/markdown

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Converts Markdown strings to HTML using the 'marked' library. Supports optional sanitization for XSS protection and gracefully handles invalid input.

```javascript
import { markdownToHtml } from '@cloudcreate/core/markdown';
// or:
import { markdownToHtml } from '@cloudcreate/core';

// Basic rendering
const html = markdownToHtml('# Hello\n\nThis is **bold** and _italic_.');
console.log(html);
// → <h1>Hello</h1><p>This is <strong>bold</strong> and <em>italic</em>.</p>

// With a sanitizer to strip <script> tags (e.g., using DOMPurify)
import DOMPurify from 'dompurify';
const safeHtml = markdownToHtml('Click [here](javascript:void(0))', {
  sanitizer: (raw) => DOMPurify.sanitize(raw),
});

// Graceful fallback
console.log(markdownToHtml(null));  // → ""
console.log(markdownToHtml(123));   // → ""
```

--------------------------------

### getBrowserTool(tool) / normalizeBrowserTool(tool)

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Provides utilities to normalize tool aliases to their canonical IDs and retrieve metadata for browser tools.

```APIDOC
## getBrowserTool(tool) / normalizeBrowserTool(tool)

### Description
Resolve tool IDs and paths. `normalizeBrowserTool` normalizes aliases to canonical IDs, and `getBrowserTool` retrieves tool metadata.

### Parameters
- **tool** (string) - The tool identifier or alias.

### Request Example
```js
import { browser } from '@cloudcreate/core';

// Normalize aliases to canonical IDs
console.log(browser.normalizeBrowserTool('minify'));    // → "css:minify"
console.log(browser.normalizeBrowserTool('md'));        // → "markdown:html"
console.log(browser.normalizeBrowserTool('favicon'));   // → "image:favicon"

// Get tool metadata
const tool = browser.getBrowserTool('archive:decompress');
console.log(tool);  // → { id: "archive:decompress", path: "/archive/decompress" }

console.log(browser.getBrowserTool('unknown')); // → null
```
```

--------------------------------

### `compressBrotliBytes(file)` / `compressBrotli(file)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Compresses a single file using Brotli compression. This function utilizes `node:zlib` in Node.js and `brotli-wasm` in browsers. Both underlying implementations are loaded lazily and cached after the first call.

```APIDOC
## `compressBrotliBytes(file)` / `compressBrotli(file)`

### Description
Uses `node:zlib` in Node.js and `brotli-wasm` in browsers. Both paths are loaded lazily and cached after the first call.

### Parameters
- `file` (Uint8Array | Blob) - The data to compress.

### Returns
- `Promise<Uint8Array>` (for `compressBrotliBytes`)
- `Promise<Blob>` (for `compressBrotli` in browser)

### Example
```js
import { archive } from '@cloudcreate/core';

const data = new TextEncoder().encode('Highly repetitive content aaaaaaa...');
const brBytes = await archive.compressBrotliBytes(data);
console.log(brBytes instanceof Uint8Array); // → true
```
```

--------------------------------

### `getImageFormatFromNameAndMime(name, mime)` / `getFormatFromFile(file)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Detects the image format from a filename and/or MIME type string, normalizing common variations.

```APIDOC
## `getImageFormatFromNameAndMime(name, mime)` / `getFormatFromFile(file)` — Detect image format

### Description
Infers the image format from a filename and/or MIME type string, normalizing `jpg` → `jpeg`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { image } from '@cloudcreate/core';

console.log(image.getImageFormatFromNameAndMime('photo.jpg', ''));         // → "jpeg"
console.log(image.getImageFormatFromNameAndMime('', 'image/webp'));        // → "webp"
console.log(image.getImageFormatFromNameAndMime('unknown.bin', 'image/avif')); // → "avif"

// From a File object
const fmt = image.getFormatFromFile(new File([''], 'banner.png', { type: 'image/png' }));
console.log(fmt); // → "png"
```

### Response
#### Success Response (200)
- **format** (string) - The detected image format (e.g., 'jpeg', 'png', 'webp').

#### Response Example
```json
{
  "format": "jpeg"
}
```
```

--------------------------------

### CSS Module Functions

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Provides functions for basic and aggressive CSS minification, as well as CSS beautification.

```APIDOC
## minifyBasic(css)

### Description

Performs a lightweight, regex-based CSS minification by removing block comments and collapsing consecutive whitespace. Useful when a fast, dependency-free pass is preferred over full structural optimization.

### Method

`minifyBasic`

### Parameters

- **css** (string) - The CSS string to minify.

### Returns

- (string) - The minified CSS string. Returns an empty string for non-string input.

### Example

```js
import { minifyBasic } from '@cloudcreate/core/css';

const input = `
  /* Reset styles */
  body {
    margin:  0;
    padding:  0;
  }
`;

const result = minifyBasic(input);
console.log(result);
// → "body { margin: 0; padding: 0; }"

console.log(minifyBasic(null)); // → ""
```
```

```APIDOC
## minifyAggressive(css)

### Description

Passes the CSS through the `csso` optimizer for deep structural minification: property merging, rule deduplication, and shorthand expansion. Throws a descriptive `Error` on malformed input.

### Method

`minifyAggressive`

### Parameters

- **css** (string) - The CSS string to minify.

### Returns

- (string) - The aggressively minified CSS string.

### Throws

- `Error` - On malformed CSS input.

### Example

```js
import { minifyAggressive } from '@cloudcreate/core/css';

const input = `
  .button { color: red; }
  .button { background: blue; font-size: 14px; }
`;

try {
  const result = minifyAggressive(input);
  console.log(result);
  // → ".button{color:red;background:#00f;font-size:14px}"
} catch (e) {
  console.error('Minification failed:', e.message);
}
```
```

```APIDOC
## beautify(css)

### Description

Formats minified or unstructured CSS into human-readable form using `js-beautify` with 2-space indentation. Returns empty string for non-string inputs.

### Method

`beautify`

### Parameters

- **css** (string) - The CSS string to format.

### Returns

- (string) - The formatted CSS string. Returns an empty string for non-string input.

### Example

```js
import { beautify } from '@cloudcreate/core/css';

const minified = '.nav{display:flex;gap:8px}.nav a{color:#333;text-decoration:none}';

try {
  const pretty = beautify(minified);
  console.log(pretty);
  // → .nav {
  //     display: flex;
  //     gap: 8px;
  //   }
  //   .nav a {
  //     color: #333;
  //     text-decoration: none;
  //   }
} catch (e) {
  console.error('Beautify failed:', e.message);
}
```
```

--------------------------------

### Extract TAR.GZ Archive Entries

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Decompresses GZIP then walks the TAR header blocks, returning a flat array of file entries (directories are skipped). Use `decompressTarGzEntries` for Node.js and `decompressTarGz` for browser environments.

```javascript
import { archive } from '@cloudcreate/core';
import { readFileSync } from 'fs';

const buffer = readFileSync('bundle.tar.gz');
const entries = archive.decompressTarGzEntries(buffer);

entries.forEach(({ name, size, data }) => {
  console.log(`${name} (${size} bytes)`);
  // → src/index.js (18 bytes)
  // → src/util.js (29 bytes)
});
```

--------------------------------

### `decompressZipEntries(buffer)` / `decompressZip(buffer)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Extracts a ZIP archive. `decompressZipEntries` returns an array of objects, each containing `name`, `size`, and `data` (Uint8Array). `decompressZip` additionally attaches a `blob` property to each entry for browser convenience.

```APIDOC
## `decompressZipEntries(buffer)` / `decompressZip(buffer)`

### Description
`decompressZipEntries` returns an array of `{ name, size, data: Uint8Array }` objects. `decompressZip` additionally attaches a `blob` property to each entry for browser convenience.

### Parameters
- `buffer` (Uint8Array | ArrayBuffer) - The buffer containing the ZIP archive data.

### Returns
- `Array<{ name: string, size: number, data: Uint8Array, blob?: Blob }>`

### Example
```js
import { archive } from '@cloudcreate/core';

// Assume zipBuffer is a Uint8Array or ArrayBuffer from fetch / fs.readFileSync
const entries = archive.decompressZipEntries(zipBuffer);

for (const { name, size, data } of entries) {
  console.log(`${name} — ${size} bytes`);
  // → hello.txt — 13 bytes
  // → config.json — 15 bytes
}

// Decode a specific text file
const txt = entries.find(e => e.name === 'hello.txt');
console.log(new TextDecoder().decode(txt.data)); // → "Hello, world!"
```
```

--------------------------------

### Compress Raw Image Bytes (Node.js/Browser)

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

This function is for server-side or CLI image compression. It accepts raw image bytes (ArrayBuffer or Uint8Array) and requires explicit format hints for source and target.

```javascript
import { image } from '@cloudcreate/core';
import { readFileSync, writeFileSync } from 'fs';

const input = readFileSync('photo.png');

const { buffer, mime, ext, width, height } = await image.compressImageBytes(input, {
  sourceFormat: 'png',
  targetFormat: 'avif',
  quality: 70,
});

writeFileSync(`photo.${ext}`, Buffer.from(buffer));
console.log(`Saved as ${ext} (${mime}), ${width}×${height}`);
// → Saved as avif (image/avif), 1920×1080
```

--------------------------------

### Brotli Compress File Bytes

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Uses `node:zlib` in Node.js and `brotli-wasm` in browsers. Both paths are loaded lazily and cached after the first call. Use `compressBrotliBytes` for Node.js and `compressBrotli` for browser environments.

```javascript
import { archive } from '@cloudcreate/core';

const data = new TextEncoder().encode('Highly repetitive content aaaaaaa...');
const brBytes = await archive.compressBrotliBytes(data);
console.log(brBytes instanceof Uint8Array); // → true
```

--------------------------------

### Update Package Version

Source: https://github.com/cloudcreate-ai/cloudcreate-lib/blob/main/RELEASE.md

Use this command to update the package version according to semver rules (patch, minor, or major). The --no-git-tag-version flag prevents automatic Git tagging.

```bash
npm version <patch|minor|major> --no-git-tag-version
```

--------------------------------

### `encodeImage(imageData, targetFormat, quality?)`

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Encodes raw ImageData into a specified image format. Returns the image buffer, MIME type, and file extension.

```APIDOC
## `encodeImage(imageData, targetFormat, quality?)` — Encode raw ImageData to a format

### Description
Low-level encode from an `ImageData` object. Returns `{ buffer, mime, ext }`. For PNG, prefer `encodePngQuantized` for palette-based compression.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **imageData** (object) - The image data object with `data`, `width`, and `height` properties.
- **targetFormat** (string) - The desired output image format (e.g., 'webp', 'jpeg').
- **quality** (number) - Optional. The compression quality (0-100), primarily for lossy formats like JPEG and WebP.

### Request Example
```javascript
import { image } from '@cloudcreate/core';

// imageData: result of decodeImage or canvas.getImageData()
const { buffer, mime, ext } = await image.encodeImage(imageData, 'webp', 85);
// buffer: ArrayBuffer, mime: "image/webp", ext: "webp"
```

### Response
#### Success Response (200)
- **buffer** (ArrayBuffer) - The encoded image data.
- **mime** (string) - The MIME type of the encoded image.
- **ext** (string) - The file extension for the encoded image.

#### Response Example
```json
{
  "buffer": "ArrayBuffer object",
  "mime": "image/webp",
  "ext": "webp"
}
```
```

--------------------------------

### Quantized PNG Encoding

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Performs quantized PNG encoding using UPNG, reducing the color palette to create smaller files. The quality parameter controls the number of colors (32-256).

```javascript
import { image } from '@cloudcreate/core';

const { buffer, mime, ext } = image.encodePngQuantized(imageData, 60);
// quality 60 → ~166 colors → smaller PNG
console.log(mime); // → "image/png"
```

--------------------------------

### GZIP Compress File Bytes

Source: https://context7.com/cloudcreate-ai/cloudcreate-lib/llms.txt

Compresses a single file-like entry to GZIP format. Stores the original filename in the GZIP header when provided. Use `compressGzipBytes` for Node.js and `compressGzip` for browser environments.

```javascript
import { archive } from '@cloudcreate/core';

const data = new TextEncoder().encode('Large text content to compress...');

const gzBytes = await archive.compressGzipBytes(data, 'output.txt');
console.log(gzBytes instanceof Uint8Array); // → true

// Browser: returns a Blob with type application/gzip
const blob = await archive.compressGzip(data, 'output.txt');
```