FOSSBilling · admdly · May 28, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/src/content/docs/admin-guide/company.mdoc b/src/content/docs/admin-guide/company.mdoc
@@ -20,12 +20,12 @@ Upload the logo assets FOSSBilling should use across the interface:
 
 ### Best Practices
 
-- Store logos in your theme's `assets/` folder
+- Upload custom logos through the settings page so updates do not overwrite them
 - Use SVG for crisp display at any size
 - Keep file sizes reasonable (< 500KB)
 
 {% aside type="caution" %}
-Don't edit `themes/huraga/assets/img/logo.svg` directly — it's overwritten on updates. Upload your logo through the settings page instead.
+Don't edit the bundled files in `public/branding/` directly. They are default assets and may be overwritten on updates. Upload your logo through the settings page instead.
 {% /aside %}
 
 ### Logo Not Showing?

diff --git a/src/content/docs/extensions-and-development/file-structure.mdoc b/src/content/docs/extensions-and-development/file-structure.mdoc
@@ -18,6 +18,13 @@ Runtime data storage:
 
 This directory should be writable by the web server.
 
+### `/src/public`
+
+Public core assets that must be web-accessible:
+- **Assets** — Shared built browser assets (`/public/assets`), including the API wrapper, shared runtime, Markdown CSS, and CKEditor bundle
+- **Branding** — Default logo, dark logo, and favicon (`/public/branding`)
+- **Gateway icons** — Payment gateway logos (`/public/gateways`)
+
 ### `/src/install`
 
 The installation wizard. Automatically deleted after installation unless `APP_ENV=dev` is set.
@@ -28,7 +35,7 @@ Core PHP classes and business logic.
 
 #### `/src/library/Api`
 
-Core API files including the JavaScript wrapper (`API.js`). [See the wrapper docs](/extensions-and-development/javascript/).
+Core PHP API files. The browser-side API wrapper source now lives in `/frontend/core/api.js` and builds to `/src/public/assets/js/api.js`. [See the wrapper docs](/extensions-and-development/javascript/).
 
 #### `/src/library/Box`
 
@@ -87,6 +94,19 @@ These are for shared hosting control panels. For VPS or game servers, consider c
 
 Translations as a Git submodule. Pointing to [github.com/FOSSBilling/locale](https://github.com/FOSSBilling/locale).
 
+### `/frontend`
+
+Shared frontend source and build tooling:
+
+| Path | Purpose |
+|------|---------|
+| `core/` | Shared browser runtime and API wrapper source |
+| `editor/` | CKEditor integration source |
+| `styles/` | Shared CSS such as Markdown rendering styles |
+| `tools/` | Common esbuild, Sass, PostCSS, asset copy, and PurgeCSS helpers used by theme builds |
+
+The root `npm run build` command builds this directory into `/src/public/assets`.
+
 ### `/src/modules`
 
 All modules live here. Each module is a self-contained unit of functionality.
@@ -122,6 +142,7 @@ Theme structure:
 ```
 theme-name/
 ├── assets/                 # CSS, JS, images (built via esbuild)
+│   └── build/              # Generated theme assets and manifest
 ├── config/
 │   └── settings.html.twig  # Theme settings UI
 ├── html/                   # Twig templates

diff --git a/src/content/docs/extensions-and-development/guides/creating-a-theme.mdoc b/src/content/docs/extensions-and-development/guides/creating-a-theme.mdoc
@@ -30,7 +30,8 @@ themes/mytheme/
 ├── assets/                     # CSS, JS, images (built via esbuild)
 │   ├── css/
 │   ├── js/
-│   └── img/
+│   ├── img/
+│   └── build/               # Generated assets and manifest
 ├── config/
 │   └── settings.html.twig      # Theme settings UI (optional)
 ├── html/                       # Your templates
@@ -122,10 +123,19 @@ FOSSBilling provides [custom filters](/extensions-and-development/twig-filters)
 {{ price | format_currency(currency.code) }} {# Format currency #}
 {{ 'client/manage' | url(area: 'admin') }}   {# Admin panel link #}
 {{ 'css/theme.css' | asset_url }}            {# Theme asset URL #}
+{{ 'js/api.js' | public_asset_url }}         {# Shared core asset URL #}
 {{ date | timeago }}                         {# "2 hours ago" #}
 {{ content | markdown_to_html }}             {# Parse Markdown #}
 ```
 
+Custom layouts that do not extend the bundled themes should load the shared runtime and API wrapper before theme JavaScript:
+
+```twig
+{{ 'js/fossbilling.js'|public_asset_url|script_tag }}
+{{ 'js/api.js'|public_asset_url|script_tag }}
+<script src="{{ 'build/js/mytheme.js'|asset_url }}"></script>
+```
+
 ## Security Best Practices
 
 - Use `htmlspecialchars` when outputting user data

diff --git a/src/content/docs/extensions-and-development/javascript.mdoc b/src/content/docs/extensions-and-development/javascript.mdoc
@@ -19,7 +19,8 @@ If you're building themes or modules, use this wrapper instead of making raw bro
 The bundled admin and Huraga themes already load the wrapper. For a custom theme, add this to your base layout before your theme JavaScript:
 
 ```twig
-{{ "Api/API.js"|library_url|script_tag }}
+{{ 'js/fossbilling.js'|public_asset_url|script_tag }}
+{{ 'js/api.js'|public_asset_url|script_tag }}
 <script src="{{ 'build/js/mytheme.js'|asset_url }}"></script>
 ```
 

diff --git a/src/content/docs/extensions-and-development/twig-filters.mdoc b/src/content/docs/extensions-and-development/twig-filters.mdoc
@@ -50,7 +50,7 @@ Project-specific filters and functions are defined in these classes:
 | Filter | Description |
 |--------|-------------|
 | `asset_url` | Get the URL for a theme asset. |
-| `library_url` | Get the URL for the library folder. |
+| `public_asset_url` | Get the URL for a shared core public asset built into `/public/assets`. |
 | `mod_asset_url` | Get the URL for a module asset. Use the asset path as the filtered value and the module name as the argument. |
 | `script_tag` | Generate an HTML `<script>` tag. |
 | `stylesheet_tag` | Generate an HTML `<link>` tag for CSS. |
@@ -74,6 +74,7 @@ Project-specific filters and functions are defined in these classes:
 | `svg_sprite` | Render the current theme's SVG icon sprite when available. |
 | `has_permission` | Check whether the logged-in admin has a module permission. |
 | `antispam_honeypot` | Return the antispam honeypot configuration array. |
+| `wysiwyg` | Load and initialize the shared CKEditor bundle for a selector. |
 
 ## Usage Examples
 
@@ -98,13 +99,17 @@ Project-specific filters and functions are defined in these classes:
 {# Theme and module assets #}
 <link rel="stylesheet" href="{{ 'css/theme.css'|asset_url }}">
 <script src="{{ 'js/widget.js'|mod_asset_url('Example') }}"></script>
+{{ 'js/api.js'|public_asset_url|script_tag }}
 
-{# API form handled by Api/API.js #}
+{# API form handled by the shared API wrapper #}
 <form action="{{ 'profile/update'|api_url }}" {{ fb_api_form({ message: 'Saved'|trans }) }}>
   <input type="text" name="first_name">
   <button type="submit">{{ 'Save'|trans }}</button>
 </form>
 
+{# Shared editor bundle #}
+{{ wysiwyg('.editor-textarea') }}
+
 {# API link with a confirmation modal #}
 <a href="{{ 'client/delete'|api_url(query: { id: client.id }, role: 'admin') }}"
    {{ fb_api_link({ modal: { type: 'confirm', title: 'Are you sure?'|trans }, reload: true }) }}>

diff --git a/src/content/docs/getting-started/building.mdoc b/src/content/docs/getting-started/building.mdoc
@@ -14,7 +14,7 @@ Build FOSSBilling from source when you want to contribute code, test changes loc
 Make sure you have:
 - PHP 8.3 or newer
 - [Composer](https://getcomposer.org/) (latest version)
-- [Node.js](https://nodejs.org/) (LTS version) with npm
+- [Node.js](https://nodejs.org/) with npm 11 or newer
 {% /aside %}
 
 ## Build Steps
@@ -46,6 +46,8 @@ Make sure you have:
    npm run build
    ```
 
+   This builds the shared frontend assets into `src/public/assets` and builds the bundled `admin_default` and `huraga` theme assets.
+
 5. **Add translations** (optional)
 
    Download the [latest translations](https://github.com/FOSSBilling/locale/releases/tag/latest) and extract to `src/locale/`, overwriting existing files.
@@ -54,13 +56,19 @@ After these steps, your checkout is ready for local development or for packaging
 
 ## Development Mode
 
-For active development:
+For active theme development, use the theme workspace scripts:
 
 ```bash
-npm run dev
+npm run build-admin_default
+npm run build-huraga
 ```
 
-This watches files and rebuilds automatically when you make changes.
+The Huraga theme also supports watch mode:
+
+```bash
+cd src/themes/huraga
+npm run dev
+```
 
 ## Running Locally
 
@@ -71,4 +79,4 @@ cd src
 php -S localhost:8000
 ```
 
-Then visit `http://localhost:8000` in your browser.
+Then visit `http://localhost:8000` in your browser.
diff --git a/src/content/docs/getting-started/installation.mdoc b/src/content/docs/getting-started/installation.mdoc
@@ -76,8 +76,8 @@ server {
 		return 403;
 	}
 
-	# Deny access to /data, except /assets/gateways
-	location ~* /data/(?!(assets/gateways/)) {
+	# Deny access to runtime data
+	location ^~ /data/ {
 		return 403;
 	}
 

diff --git a/src/content/docs/maintenance/changelog.mdoc b/src/content/docs/maintenance/changelog.mdoc
@@ -27,10 +27,10 @@ For the latest changes, start with the [most recent release](https://github.com/
 | **Configuration** | New `rate_limiter` block replaces old `api.rate_*` keys; new `trusted_proxies` and `auto_detect_locale` settings |
 | **Modules** | `Antispam` replaces `Spamchecker`; `Servicemembership`, `Paidsupport`, `Wysiwyg` removed; new `Widgets` module |
 | **Templates** | All module templates moved from `html_*` to `templates/{admin,client,email}/` |
-| **Build** | Front-end asset build migrated from webpack to esbuild |
+| **Build** | Front-end asset build migrated from webpack to esbuild; shared frontend source now lives in `/frontend` and builds into `/src/public/assets` |
 | **Library** | New Doctrine ORM layer alongside RedBean; Symfony Rate Limiter, Uid, Sanitizer, Serializer, PropertyAccess components added; `Box_Mod`, `Box_Paginator`, `Box_TwigExtensions` removed |
-| **Patcher** | Extended through patch 63 (was 43) |
-| **Uploads** | Moved from `/uploads` to `/data/uploads` |
+| **Patcher** | Extended through patch 64 (was 43) |
+| **Uploads & Public Assets** | Uploads moved from `/uploads` to `/data/uploads`; gateway and default branding assets moved to `/public` |
 
 [View the full 0.8.0 release notes](https://github.com/FOSSBilling/FOSSBilling/releases/latest) for the complete list of changes.
 

diff --git a/src/content/docs/maintenance/updating.mdoc b/src/content/docs/maintenance/updating.mdoc
@@ -71,7 +71,7 @@ The uploads directory has moved from `/uploads` to `/data/uploads`. Files are mi
 location ~* /uploads/.*\.php$ { return 403; }
 
 # Updated for 0.8.0:
-location ~* /data/(?!(assets/gateways/)) { return 403; }
+location ^~ /data/ { return 403; }
 ```
 {% /tabitem %}
 {% tabitem label="Apache (.htaccess)" %}
@@ -91,14 +91,21 @@ Module templates have been moved from the old `html_*` directory names to a `tem
 
 The patcher removes the old `html_*` directories from modules. If you have custom modules, **update your file structure before applying the patches**, or the old directories will be deleted and you will lose your changes.
 
+### Public Assets
+
+Shared browser assets now live in `/public` instead of `/data/assets` or theme-specific fallback paths:
+
+| Asset | New location |
+|-------|--------------|
+| Gateway icons | `/public/gateways/` |
+| Default logo, dark logo, and favicon | `/public/branding/` |
+| Shared JavaScript, Markdown CSS, and CKEditor bundles | `/public/assets/` |
+
+The patcher migrates bundled gateway icons and default branding settings automatically. If you maintain custom web-server rules, make sure `/public` remains publicly readable while `/data` remains blocked.
+
+Custom themes should load shared frontend assets with `public_asset_url`, for example `{{ 'js/api.js'|public_asset_url|script_tag }}`. The old `library/Api/API.js` path has been removed.
+
 ### Encryption Format Update
 
 Custom payment adapters or modules that store encrypted data using FOSSBilling's encryption may need their data re-encrypted after the update. The patcher (patch 50) handles this migration automatically for core data, but custom implementations should be verified.
 
-### Post-Upgrade Checklist
-
-- [ ] Review spam/anti-spam settings (`Antispam` module replaces `Spamchecker`)
-- [ ] Review active membership orders migrated to custom products
-- [ ] Update web-server rules if you have custom NGINX/Apache configs
-- [ ] Verify custom modules use the new `templates/` directory structure (custom themes are unaffected)
-- [ ] Clear the cache: **System → Tools → Clear cache**