# bt:// protocol

## Function
`bt://` is the project resource protocol used by `bt_app` internally for WebView. It maps files in the project directory or package bundle to URLs accessible to the page.

```text
bt://app/
bt://app/index.html
bt://app/assets/app.css
bt://app/main.js
```

This protocol is not a system-level external protocol and is not used to allow the operating system or ordinary browsers to open BT applications. It only takes effect inside the WebView created by `bt_app`.

## Usage
 In `static` mode, `app.entry` can be written as a relative path: The project resources can be explicitly referenced in the

```json
{
  "app": {
    "mode": "static",
    "entry": "index.html"
  }
}
```

 page:

```html
<link rel="stylesheet" href="bt://app/assets/app.css">
<script src="bt://app/assets/app.js"></script>
<img src="bt://app/assets/logo.png">
```

## Path rules
- `bt://app/` will be mapped to the current `static` entry file, the default is `index.html`.
 - The hostname must be `app`, for example `bt://app/index.html`.
- The path is relative within the project.
 - Absolute path cannot be accessed.
- Cannot contain `..`.
- Development mode reads the project directory file, and packaging mode reads the exe tail Bundle.
- In `static` mode, the path without extension will fall back to the entry HTML when the resource does not exist, for compatibility with SPA history routing; when the resource with extension does not exist, a resource error will still be returned.

## The Content-Type
 protocol returns common Content-Types by extension:

| Extension | Type |
|---|---|
| `.html` `.htm` | `text/html; charset=utf-8` |
| `.css` | `text/css; charset=utf-8` |
| `.js` | `application/javascript; charset=utf-8` |
| `.json` | `application/json; charset=utf-8` |
| Corresponding image type |
| `.wasm` | `application/wasm` |
| `.txt` | `text/plain; charset=utf-8` |

## When debugging
 and need to view the protocol request, you can set the environment variable:

```bash
set BT_APP_TRACE_PROTOCOL=1
./bt_app.exe run
```

## Common errors
- `资源路径无效`: The URL path contains illegal encoding or is not a safe relative path.
- `资源不存在或无法读取`: The file is not placed in the project directory, or does not enter the Bundle when packaging.
 - `403`: The protocol host is not `app`, or the path is trying to access outside the project.