Feat: Creating vite-plugin.js for boboko/core

CONTRIBUTE.md

@@ -31,6 +31,56 @@ This is shorthand for `docker compose -f docker-compose.dev.yml -f docker-compos
 
    Skipping this step is the most common cause of "my change isn't showing up."
 
+## JS/CSS: no separate npm package
+
+This package's JS (Stimulus controllers) and CSS ship as plain source files under `resources/js/` and `resources/css/`, read directly by a consumer app's own Vite build — there is no separate `@boboko/core` npm package, and no `npm install`/`file:` dependency step of any kind.
+
+The reason: Composer already gives every environment one single, unconditional path — `vendor/boboko/core` — whether that resolves to a real symlink into `../boboko-core` (local path repo) or a real installed copy (tagged VCS release). A consumer's `vite.config.js` and JS entry point just read straight from that path, so there is nothing to toggle on the JS side — whatever Composer resolved is exactly what Vite sees, automatically, in both dev and prod.
+
+**Stable entry point.** A consumer imports from [resources/js/index.js](resources/js/index.js) only — never from a path reaching into a specific module's internals (e.g. `resources/js/checkout/index.js` directly). That barrel file re-exports whatever a consumer needs (currently just `registerCheckout`), so this package's internal file layout can change without breaking every consumer's own entry point:
+
+```js
+// consumer app's resources/js/app.js
+import { registerCheckout } from "../../vendor/boboko/core/resources/js/index.js";
+registerCheckout(application);
+```
+
+```php
+{{-- consumer app's layout --}}
+@vite(['vendor/boboko/core/resources/css/checkout.css', 'resources/css/app.css', 'resources/js/app.js'])
+```
+
+**What a consumer's `vite.config.js` needs**, because `vendor/boboko/core` is a symlink in local path-repo dev (not a real directory):
+
+```js
+export default defineConfig({
+    server: {
+        watch: {
+            // vendor/boboko/core is a symlink into ../boboko-core in local
+            // path-repo dev. Vite/chokidar don't follow symlinks for watched
+            // files by default, so edits to core's source wouldn't otherwise
+            // trigger HMR. No-op against a real installed copy (tagged VCS
+            // release) in production — there's no symlink to follow, and
+            // production only ever runs a one-shot `npm run build`, which
+            // doesn't watch anything regardless.
+            followSymlinks: true,
+        },
+    },
+});
+```
+
+Bare imports inside this package's own JS (`leaflet`, `@hotwired/stimulus`) resolve against the *consumer's* `node_modules` — Node's normal upward `node_modules` resolution walks from `vendor/boboko/core/resources/js/...` up through `vendor/boboko/`, `vendor/`, to the consumer app's root, where `node_modules` lives. This works with zero extra config as long as `vendor/boboko/core` sits inside the consumer's own directory tree (true for both the symlink and the real-copy case) — a consuming app's `vite`-equivalent Docker service just needs the same bind mount PHP containers already get, landing at the same path:
+
+```yaml
+# consumer app's docker-compose.core-dev.yml
+services:
+  vite:
+    volumes:
+      - ../boboko-core:/app/vendor/boboko/core
+```
+
+(Match whatever the consumer's Vite container's working directory actually is — `/app` above, `/var/www/html` for the PHP containers in `boboko-test`'s convention.)
+
 ## Verifying changes against a real database
 
 There is no automated test suite for this package — too much of Lunar's behavior (table prefixing, nested sets, translatable attributes, Filament panel filters) only breaks in combination, against real Postgres, in a way that's impractical to fake in isolation. Instead, verify changes directly against a consumer app's live database. The practical workflow used throughout this package's `MigrateImport` feature: