chore(release): 0.25.0

.github/workflows/release.yml

@@ -140,13 +140,21 @@ jobs:
           # along in a release built from it. The three bundled examples are
           # tracked source and stay — the include rules come first because rsync
           # takes the first matching rule.
+          #
+          # Every pattern is ANCHORED with a leading slash, meaning
+          # backend/modules and nothing else. Without it rsync matches a
+          # directory called `modules` at any depth, and this repository has a
+          # second one: resources/js/Pages/admin/modules. Unanchored, these rules
+          # stripped the Modules admin screen out of every release — so the one
+          # screen that installs a module was missing from the package, and the
+          # UI answered "Page unavailable" with no way to tell why.
           rsync -a backend/ "${DIST}/backend/" \
-            --include='modules/' \
-            --include='modules/README.md' \
-            --include='modules/ExampleHooks/***' \
-            --include='modules/ExampleShowcase/***' \
-            --include='modules/OrderPinger/***' \
-            --exclude='modules/*' \
+            --include='/modules/' \
+            --include='/modules/README.md' \
+            --include='/modules/ExampleHooks/***' \
+            --include='/modules/ExampleShowcase/***' \
+            --include='/modules/OrderPinger/***' \
+            --exclude='/modules/*' \
             --exclude='.env' \
             --exclude='node_modules' \
             --exclude='tests' \
@@ -172,6 +180,28 @@ jobs:
           mkdir -p "${DIST}/backend/storage/framework/views"
           touch "${DIST}/backend/storage/logs/.gitkeep"
 
+          # Every tracked file under backend/resources/ has to be in the package.
+          #
+          # This is the check that was missing when an unanchored rsync exclude
+          # quietly dropped resources/js/Pages/admin/modules — three files out of
+          # 228, in a package nobody counts by hand. The Dockerfile check below
+          # did not catch it: the directory it copies was there, only emptied.
+          #
+          # resources/ is entirely source that ships; anything excluded from it
+          # is a mistake by definition, which is what makes this safe to assert.
+          missing_resources=0
+          while read -r tracked; do
+            rel="${tracked#backend/}"
+            if [ ! -e "${DIST}/backend/${rel}" ]; then
+              echo "::error::${tracked} is tracked but missing from the release package"
+              missing_resources=$((missing_resources + 1))
+            fi
+          done < <(git ls-files backend/resources)
+          if [ "$missing_resources" -ne 0 ]; then
+            echo "::error::${missing_resources} tracked file(s) under backend/resources did not make it into the package"
+            exit 1
+          fi
+
           # The package promises `docker compose up -d --build` works from the
           # unpacked folder, so every path the Dockerfile copies has to be in it.
           # Nothing compared these two files before, which is how v0.22.0 shipped

CLAUDE.md

@@ -30,7 +30,7 @@ docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d   # dev ove
 
 ## Hard rules
 
-1. **English-first** — all code, Blade/JSX text, validation messages, seeders, comments are English. Other languages exist only as translations in `backend/lang/*.json`.
+1. **English-first** — all code, Blade/JSX text, validation messages, seeders, comments are English. Other languages exist only as translations in `backend/lang/*.json`. This covers **everything published to this repository**, not only code: pull request titles *and* descriptions, issue comments, commit messages, README and docs. This repo is public and read by people who do not share your first language.
 2. **i18n parity** — `lang/en.json` and `lang/pl.json` must contain the same key set. Adding a UI string means adding the key to **both** files (English value = key itself in `en.json`). These are strict JSON: **no trailing comma** on the last entry, or `json_decode` fails and the whole UI silently falls back to English. New keys are appended, so the files conflict on almost every merge — resolve with `.claude/skills/i18n-lang-files/`, never by hand-editing the conflict markers (a text-level union resurrects deliberately deleted keys and duplicates others).
 3. **Form Requests for validation** — never validate inline in controllers. Frontend validation is UX only; the backend rule set is authoritative.
 4. **Never rename migration filenames after merge** — the filename is the migration's identity; renaming breaks every existing database on upgrade (duplicate-table crash in the entrypoint migrate).

HOOKS.md

@@ -29,6 +29,7 @@ Three reference modules ship in the repo (all disabled by default):
   - [Scheduling hook — `WorkOrderScheduled`](#scheduling-hook--workorderscheduled)
 - [2. Menu hooks](#2-menu-hooks)
 - [3. Dashboard widget hooks](#3-dashboard-widget-hooks)
+- [4. Page display hooks and filters](#4-page-display-hooks-and-filters)
 - [Enabling a module](#enabling-a-module)
 - [Best practices](#best-practices)
 - [Complete hook reference](#complete-hook-reference)
@@ -227,6 +228,63 @@ $menu->addGroupItem('yourmod', 'Overview', url('/modules/your-module'), order: 1
 Resolve URLs with `url()` (not `route()`) so registration never depends on route
 load order or a cached route table.
 
+Every entry a module contributes is tinted with the accent colour in the sidebar,
+and lights up as active on its own pages (the registered URL is matched by path).
+
+### Operator panel tabs
+
+A module that ships an operator screen registers it as a tab on the operator
+top bar, next to Queue / Workstation:
+
+```php
+// label, url, order (built-in tabs are 10 and 20), optional path prefix that
+// keeps the tab highlighted (defaults to the link's own path).
+$menu->addOperatorItem('Team', url('/operator/team'), order: 30);
+```
+
+Operator tabs are Inertia links — the page behind them is a React page under the
+module's `resources/js/Pages/`. They arrive in the browser as `moduleNav.operator`
+and render tinted like sidebar entries.
+
+### Translations
+
+A module's own strings live in `modules/<Name>/lang/<locale>.json` (the same
+source-string-keyed shape as core's `lang/*.json`). The frontend merges them
+under the core file at bootstrap — a module can add strings, never redefine a
+core one — and the provider loads the same directory for PHP:
+
+```php
+$this->loadJsonTranslationsFrom(__DIR__.'/../lang');
+```
+
+### Import entities
+
+`ImportRegistry` (Admin → Import) accepts importers from modules through the
+`import.entities` filter:
+
+```php
+app(FilterRegistry::class)->addFilter('import.entities', fn ($e) => [...$e, MyImporter::class]);
+```
+
+`MyImporter` extends `App\Import\AbstractEntityImporter`; the screen, the queued
+job, the sample file and the routes pick it up.
+
+### Testing a module
+
+`Tests\Support\ModuleTestCase` registers the module's provider on each test's
+fresh application and migrates the module's directory inside the test
+transaction (the suite's `migrate:fresh` runs before any provider boots, so a
+module's tables are never part of that schema):
+
+```php
+class MyModuleTest extends \Tests\Support\ModuleTestCase
+{
+    protected string $module = 'MyModule';
+    protected string $provider = \Modules\MyModule\Providers\MyModuleServiceProvider::class;
+    protected string $probeTable = 'my_module_things';
+}
+```
+
 ## 3. Dashboard widget hooks
 
 `App\Services\WidgetRegistry` lets a module add cards to the admin dashboard.
@@ -251,6 +309,81 @@ KPIs; `main` renders as a full-width card at the bottom of the dashboard column.
 
 ---
 
+## 4. Page display hooks and filters
+
+`App\Extension\HookRegistry` carries contributions to named points on a page; the
+controller that owns the page resolves its points with `renderMany()` and hands them
+over as the `hooks` prop, and the page renders `<Hook name=… hooks={hooks} …context />`
+from `resources/js/lib/hooks.jsx`. `App\Extension\FilterRegistry` lets a module
+change a value core computed. With no module listening, a page is sent `{}` and every
+filter returns its default — a community install renders exactly what it did before.
+
+A point that **replaces** a core control (marked below) checks `hasHook()` first and
+skips its own control when a module contributed.
+
+```php
+app(HookRegistry::class)->listen('display.operator.work_order.sections', fn (array $ctx) => [
+    'title' => 'Recipe vs weighed',
+    'body'  => Recipe::summary($ctx['workOrderId']),
+]);
+
+app(FilterRegistry::class)->addFilter('operator.can_logout', fn (bool $can, array $ctx) => $can && ! Panel::isShared($ctx['user']));
+```
+
+> A `component` (`ext:<Dir>/<Name>`, resolved under
+> `modules/<Name>/resources/js/Components/`) only exists in a build that contained
+> the module. A module installed from a ZIP into a released install must contribute
+> the plain card fields instead.
+
+### Display hooks
+
+```
+display.operator.workstation.shift_cell   context: entry, workOrder, shift, canCorrect   (replaces the whole shift cell)
+display.operator.work_order.sections      context: workOrder                 (rendered after the BOM section)
+display.operator.quantity_field           props: value, onChange, variant     (replaces the operator's number input, page-wide)
+display.operator.layout                   (no context)                        (rendered at the top of every operator screen)
+display.settings.system.tabs              contribution: slot, title, component (one tab each on Settings → System)
+```
+
+The PHP-side context a listener receives:
+
+| Hook | Resolved by | PHP context |
+|---|---|---|
+| `display.operator.workstation.shift_cell` | `Operator\WorkstationController::index` | `line`, `workstation`, `lineId`, `workstationId` |
+| `display.operator.work_order.sections` | `Operator\WorkOrderController::show` | `workOrderId`, `workstationId` |
+| `display.operator.quantity_field` | `WorkstationController::index`, `WorkOrderController::show` + `::queue` | same as the page's other points |
+| `display.operator.layout` | `HandleInertiaRequests` (shared `operatorHooks`) | `user` |
+| `display.settings.system.tabs` | `SettingsController::showSystemSettings` | — |
+
+Notes:
+
+- **`quantity_field`** — `QuantityField.jsx` renders the first contribution's
+  component with `value`, `onChange(value)` (the value, not an event), `variant`
+  (`big` for a modal's single field, `compact` inline) and every other input prop
+  (`min`, `max`, `step`, `aria-label`, …) passed through.
+- **`settings.system.tabs`** — each contribution becomes a tab with value
+  `ext-<slot>` (linkable as `?tab=ext-<slot>`) labelled `title`. Its component
+  renders outside the core settings form, so core's Save button is not shown
+  there: the module saves through its own route.
+- **`operator.layout`** is resolved on every Inertia response, like any shared
+  prop — a listener should return `null` cheaply where it has nothing to show.
+
+### Filters
+
+```
+operator.tabs          list of {key, label, url, prefixes}   the operator top bar's core tabs
+operator.module_tabs   list of {label, url, order, prefix}   module tabs, per request
+operator.can_logout    bool (default true)                   whether the operator chrome shows its logout button
+```
+
+`operator.tabs` and `operator.can_logout` receive `['user' => $user]` as context.
+`operator.module_tabs` runs over what `addOperatorItem()` registered, on every
+request, so a module can show a tab only where it applies without re-registering.
+`operator.can_logout` hides the button only — a module that forbids logout must
+still refuse the `POST /logout` itself.
+
+---
+
 ## Enabling a module
 
 1. **Admin → Modules → your module → Enable** (or add its name to the
@@ -311,6 +444,14 @@ class SyncToErp implements ShouldQueue
 **Widgets** (`App\Services\WidgetRegistry`): `register` — zones `kpi`, `main`,
 `sidebar`.
 
+**Display hooks** (`App\Extension\HookRegistry`): `display.operator.workstation.actor`,
+`display.operator.workstation.shift_cell`, `display.operator.work_order.sections`,
+`display.operator.quantity_field`, `display.operator.layout`,
+`display.settings.system.tabs`.
+
+**Filters** (`App\Extension\FilterRegistry`): `operator.tabs`,
+`operator.module_tabs`, `operator.can_logout`, `import.entities`.
+
 ---
 
 ## Support

README.md

@@ -170,7 +170,7 @@ Dedicated station for scanning finished products with a barcode reader (EAN/QR)
 
 **How it works:**
 
-1. Operator opens `/packaging/station` on a dedicated workstation or tablet
+1. Operator opens `/operator/packaging` on a dedicated workstation or tablet (supervisors and admins reach the same screen at `/packaging/station`)
 2. Scans an EAN barcode with a USB/Bluetooth reader (or types it manually)
 3. The system looks up which work order the EAN belongs to and increments its `packed_qty` counter
 4. Live stats update every 3 seconds: packed today, plan, backlog, realisation %
@@ -187,7 +187,8 @@ Dedicated station for scanning finished products with a barcode reader (EAN/QR)
 
 | URL | Access | Description |
 |---|---|---|
-| `/packaging/station` | Operator, Supervisor, Admin | Scanning station |
+| `/operator/packaging` | Operator | Scanning station (operator shell) |
+| `/packaging/station` | Supervisor, Admin | Scanning station (admin shell; operators are redirected to `/operator/packaging`) |
 | `/packaging/` | Supervisor, Admin | Admin overview |
 | `/packaging/eans` | Supervisor, Admin | EAN code management |
 

backend/.gitignore

@@ -15,11 +15,16 @@
 /auth.json
 /node_modules
 /public/build
+# Compiled frontends of installed modules, copied here by ModuleManager when a
+# module is enabled. Belongs to the installation, not to the repository.
+/public/modules
 /public/hot
 /public/storage
 /storage/*.key
 /storage/pail
 /vendor
+# Generated on every Vite build by openmesRuntime() from packages/module/contract.js.
+/resources/js/runtime.generated.js
 Homestead.json
 Homestead.yaml
 Thumbs.db

backend/Dockerfile

@@ -50,10 +50,20 @@ COPY packages/ /var/www/packages/
 # Install PHP dependencies
 RUN composer install --no-dev --optimize-autoloader --no-interaction
 
-# Fetch the RoadRunner binary for Laravel Octane (concurrent app server).
-# Placed in the project root — where Octane's RoadRunner server discovers it.
-RUN ./vendor/bin/rr get-binary --location /var/www/html \
-    && chmod +x /var/www/html/rr
+# The RoadRunner binary for Laravel Octane (concurrent app server), taken from
+# the official image rather than downloaded during the build.
+#
+# `vendor/bin/rr get-binary` asks api.github.com for the release list, which
+# makes every build depend on GitHub being reachable and on DNS answering at
+# that moment. Five services in docker-compose.yml build from this Dockerfile,
+# so a single `up --build` made that call several times over in parallel — enough
+# for a home router's resolver to return NODATA and fail the install outright.
+#
+# The version is pinned to match `spiral/roadrunner` in composer.lock. Bump both
+# together: Octane loads the PHP side from vendor and executes this binary, and
+# they are meant to be the same release.
+COPY --from=ghcr.io/roadrunner-server/roadrunner:2025.1.14 /usr/bin/rr /var/www/html/rr
+RUN chmod +x /var/www/html/rr
 
 # Install Node dependencies and build assets
 RUN npm ci && npm run build