# Installation

This guide explains how to install, build, and run AsukaDesigner v1.

## Requirements

- Node.js 20.19+ or 22.12+
- npm

## Install dependencies

```bash
npm install
```

## Available scripts

### Start the development server

```bash
npm run dev
```

### Build all main outputs

```bash
npm run build
```

This command currently chains:

- `build:lib`
- `build:product`
- `build:product-single`
- `build:browser-global`
- `build:demo`
- `typedoc`

To publish the generated JavaScript API reference inside the Asuka Studio
WordPress site, point the synchronization task at the theme directory:

```powershell
$env:ASUKA_WORDPRESS_THEME_PATH="C:\\path\\to\\wp-content\\themes\\asuka-studio"
npm run docs:wordpress
```

The task regenerates TypeDoc, copies the versioned static artifact, and writes
the manifest consumed by the `[asuka_javascript_api_docs]` shortcode.

### Build only the library bundle

```bash
npm run build:lib
```

### Build the product bundle

```bash
npm run build:product
```

### Build the single-file product bundle

```bash
npm run build:product-single
```

### Build the browser-global bundle

```bash
npm run build:browser-global
```

### Generate the TypeDoc API reference

```bash
npm run docs
```

### Run tests

```bash
npm run test
```

### Run linting

```bash
npm run lint
```

### Validate a release candidate

```bash
npm run check:release
```

This runs the static checks, shared renderer contracts, unit and browser tests,
bundle and package audits, the production dependency security audit, and creates
the verified versioned artifact in `dist/release/`.

## Production API

The built-in commercial API and license clients always use:

```text
https://api.asukadev.com
```

No Vite environment variable or hard-coded local endpoint is required by a
customer integration. Pass the license key at initialization:

```ts
createAsukaDesigner('#app', {
  license: {
    key: 'ASK-XXXX-XXXX-XXXX',
  },
});
```

The public runtime does not accept a custom commercial API URL. Development and
staging tests must redirect the official hostname at the network or test-runner
layer rather than shipping a different endpoint in customer initialization.

## Output overview

The project exposes several build targets from `package.json`:

- `.`
- `./product`
- `./demo`
- `./product-single`
- `./browser-global`

### Main library output

Use this when integrating AsukaDesigner as a package in a TypeScript or JavaScript application.

### Product output

Use this when you want the runtime-oriented bundle with lazy-loaded addons.

### Browser-global output

Use this when you want to integrate the editor in a more traditional way through globals such as:

- `createAsukaDesigner`
- `AsukaDesigner.createAsukaDesigner`

## Browser integration

The product ESM build is intended to support setups such as:

```html
<link rel="stylesheet" href="./dist/product/asukadesigner.min.css" />
<script type="module">
  import { createAsukaDesigner } from './dist/product/asukadesigner.min.js';
  const designer = createAsukaDesigner('#app', {});
</script>
```

The runtime also exposes browser globals after the module has evaluated.

## Product files

The product folder contains one main script, one Fabric script, one Babylon
script, one stylesheet, and a small stable set of optional `*-addon.js` files.
Renderer files are imported automatically. Licensed add-ons are requested only
when their entitlement is active; omitted or missing add-ons remain absent from
the UI.

## TypeDoc output

The generated API reference is currently written to:

- `docs/`

Because `docs/` is used for generated API pages, the hand-written guides live in:

- `guides/`

## See also

- [Guides index](./index.md)
- [Quick start](./quick-start.md)
- [API overview](./api-overview.md)