Bump Version to 0.6.0

CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.6.0] - 2026-08-27
+
+### Added
+- `Modules\Core\Product\Contracts\ProductOptionTypeInterface` describes how a category of `Lunar\Models\ProductOption` (e.g. "Color", "Size") behaves — what structured data its values carry in their free-form `meta` jsonb column, and how an admin edits it via Filament — without introducing a new model. Enabled per-shop as a plain list in `config('core.product_option_types')`; an admin then picks one per `ProductOption` from a "Option Type" dropdown on the option's own edit form (added by `Modules\Core\Product\Filament\Extensions\ProductOptionResourceExtension`), stored in `ProductOption::meta['option_type']` — deliberately not tied to the option's `handle`, since a shop's own handle naming shouldn't have to match a type's key. `Modules\Core\Product\Services\ProductOptionTypeManager` resolves the selected key to its type (`all()`/`resolve()`). `Modules\Core\Product\Filament\Extensions\ValuesRelationManagerExtension` hooks Lunar's own `ValuesRelationManager` (both extensions via `LunarPanel::extensions()`, registered in `CorePlugin`) to append the resolved type's meta form fields to the stock "Values" tab — no fork of Lunar's classes needed. Ships a reference implementation, `Modules\Core\Product\OptionTypes\ColorOptionType` (not auto-registered). Documented in `docs/product-options.md`.
+- `Modules\Core\Product\Observers\ProductOptionReindexObserver`, wired in the new `Modules\Core\Providers\ProductServiceProvider`, keeps Meilisearch in sync when a `ProductOption` or `ProductOptionValue` is saved or deleted — e.g. picking an Option Type or editing a color's hex. `ProductIndexer::mapVariant()` embeds each option value's `meta` directly into a product's indexed document, but saving the option/value never fires the *product's* own save events, so without this a changed hex would only reach the index on that product's next unrelated reindex. The observer resolves every `Lunar\Models\Product` whose variants use the changed option (or option value) via the `product_option_value_product_variant` pivot, and calls `->searchable()` on each.
+- `Modules\Core\Localization\Models\LanguageLine` extends `spatie/laravel-translation-loader`'s `LanguageLine` to fall back to the store's actual default language (`LanguageCache::defaultLocale()`, backed by Lunar's `languages.default` flag) instead of the package's stock behavior of falling back to the static `config('app.fallback_locale')` — the two were previously disconnected, so changing the default language via the Filament **Languages** resource had no effect on which locale an untranslated storefront label silently fell back to. Swapped in automatically via `config('translation-loader.model')` in `LocalizationServiceProvider::register()`; no consuming app changes needed. Documented in `docs/localization.md` ("Fallback locale follows the store's default language").
+
+### Changed
+- **Breaking:** `Modules\Core\Catalog\ProductService::list()` now returns a real `Illuminate\Pagination\LengthAwarePaginator` (built from the localized Meilisearch hits) instead of a plain `array{data, meta}` — gives callers normal Laravel pagination behaviour (`$products->links()`, standard JSON serialization) without ever touching Scout's raw `paginateRaw()` response directly. `getById()`/`getBySlug()` are unaffected (still return `?array`).
+- `ProductService::withLocalizedFields()` (used by `list()`, `getById()`, `getBySlug()`) no longer hardcodes `name`/`description` as the only translated fields — it now reads every `TranslatedText` attribute on `Product` from `Lunar\Base\AttributeManifest` (the same source Lunar's own indexer reads), so a store's own custom translated attributes (e.g. `seo_title`, `seo_description`) are resolved and locale-stripped automatically with no code change here. Raw `{handle}_{locale}` keys (e.g. `name_el`, `seo_title_en`) are now stripped from every returned product, not just `name_*`/`description_*`.
+- Extracted `Modules\Core\Localization\Services\LanguageCache` (cached read layer over Lunar's `languages` table: `all()`, `defaultLocale()`, `availableLocales()`, `forget()`) out of `LocaleMiddleware`, which previously owned this as private/static methods despite not being middleware-specific behavior. `LocaleMiddleware` now takes `LanguageCache` via constructor injection. `LocaleMiddleware::defaultLocale()`/`forgetLanguagesCache()` (static) are removed — use `app(LanguageCache::class)` or inject `LanguageCache` directly.
+
+### Fixed
+- `Modules\Core\MigrateImport\JudgeMe\Resolvers\ProductResolver::resolve()` picked whichever `lunar_urls` row matched a slug first, which can be a soft-deleted product left behind by an earlier import batch rather than the current live one — a store can easily end up with more than one `Product` row sharing the same slug across re-imports, since a soft-deleted product's URL row isn't cleaned up. This silently broke every downstream lookup for that handle (e.g. `Modules\Core\MigrateImport\JudgeMe\JudgeMeExportImporter` logging "no product found for handle, skipping review" and dropping the row, even though a live product with that exact handle existed). Rewrote as a join against `lunar_products` — via `Product::query()`, so Eloquent's `SoftDeletes` global scope excludes trashed rows — so only a URL pointing at a live product resolves.
+- `Modules\Core\Review\Models\ProductReview` had no `registerMediaConversions()` at all, unlike `Product`/`ProductVariant` which get one automatically from Lunar's own `Lunar\Base\StandardMediaDefinitions`. `Modules\Core\Search\ProductIndexer::mapMedia()` is shared across product, variant, and review media and always requests the `small` conversion — the first time a review had an attached image, indexing it threw `Spatie\MediaLibrary\MediaCollections\Exceptions\InvalidConversion`, silently failing the product's `MakeSearchable` queue job (and everything queued after it, since Scout batches). Added a matching `small` conversion (300×300, same fit/border/background as Lunar's standard one) directly on `ProductReview`.
+
+### Breaking
+- Merged `Modules\Core\Catalog` and `Modules\Core\Search` into a single `Modules\Core\Product` concern, since both existed purely to serve `Product` (browsing/filtering vs. indexing/full-text search — two services, one concern), following a stricter subfolder convention (`Contracts/`, `Enums/`, `Services/`, `DTOs/`, `Models/`, etc. per concern) going forward:
+  - `Modules\Core\Catalog\ProductService` → `Modules\Core\Product\Services\ProductService`
+  - `Modules\Core\Catalog\ProductFilters` → `Modules\Core\Product\DTOs\ProductFilters`
+  - `Modules\Core\Catalog\ProductSort` → `Modules\Core\Product\Enums\ProductSort`
+  - `Modules\Core\Search\ProductIndexer` → `Modules\Core\Product\Services\ProductIndexer`
+  - `Modules\Core\Search\ProductSearchService` → `Modules\Core\Product\Services\ProductSearchService`
+
+  Consuming apps must update any direct references — notably `config/lunar/search.php`'s `'indexers'` map, which points at `ProductIndexer` by FQCN. `Modules\Core\Catalog\ProductOptionTypeInterface` (in-progress, not yet wired to anything) was deliberately left in place rather than moved.
+- Reorganized `Modules\Core\Localization` under the same stricter per-concern subfolder convention — `Events/`, `Filament/`, `Listeners/` were already correctly categorized; four loose root files moved into typed buckets by structural role:
+  - `Modules\Core\Localization\LocaleMiddleware` → `Modules\Core\Localization\Middleware\LocaleMiddleware`
+  - `Modules\Core\Localization\LanguageCacheObserver` → `Modules\Core\Localization\Observers\LanguageCacheObserver`
+  - `Modules\Core\Localization\TranslationReader` → `Modules\Core\Localization\Services\TranslationReader`
+  - `Modules\Core\Localization\TranslationService` → `Modules\Core\Localization\Services\TranslationService`
+
+  `Modules\Core\Localization\Services\LanguageCache` (added earlier in this same unreleased version) already lived at its correct final path — unaffected. The `'locale'` route-middleware alias (registered in `LocalizationServiceProvider`) is unaffected for consuming apps using it by string alias rather than FQCN.
+
+## [0.5.4] - 2026-08-26
+
+### Added
+- `Modules\Core\Catalog\ProductService::list()` accepts a `sort` parameter (new `ProductSort` enum: `PriceAsc`, `PriceDesc`, `Newest`), translated into a Meilisearch `sort` clause — `list()` previously had no way to order results, since it always searches with an empty query string and so has no relevance score to fall back on. `Modules\Core\Search\ProductIndexer::getSortableFields()` now also marks `price` sortable (Lunar's base indexer only marks `created_at`/`updated_at`/`skus`/`status`). Requires re-syncing index settings (`php artisan lunar:meilisearch:setup`) on existing stores. Documented in `docs/product-listing.md` ("Sorting").
+
+## [0.5.3] - 2026-08-26
+
+### Fixed
+- `Modules\Core\Search\ProductIndexer::toSearchableArray()` threw `column reference "id" is ambiguous` on Postgres when computing `channel_ids` — `$model->channels()->wherePivot('enabled', true)->pluck('id')` joins `lunar_channels` and `lunar_channelables`, both of which have an `id` column, and the unqualified `pluck('id')` left Postgres unable to resolve which table's column to select (SQLite/MySQL tolerated the ambiguity). Qualified as `pluck('lunar_channels.id')`.
+
+## [0.5.2] - 2026-08-26
+
+### Fixed
+- `Modules\Core\Localization\LocaleMiddleware`'s shared view data only ever surfaced a single alternate locale (`altLocale`/`altLocaleUrl`, found via `firstWhere('code', '!=', $current)`) — correct by coincidence for a 2-language store, but silently dropped every locale past the first "other" one found for a 3+ language store, with no error. Replaced with `altLocales`, a collection of every other configured language (`code`, `name`, `url` for the current route each), so a language switcher or `hreflang` tags scale to any number of locales. Documented in `docs/localization.md` ("Shared view data — language switcher and `hreflang` tags").
+
 ## [0.5.1] - 2026-08-25
 
 ### Added

composer.json

@@ -2,7 +2,7 @@
   "name": "boboko/core",
   "description": "Core module — authentication and shared panel behaviour",
   "type": "library",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "autoload": {
     "psr-4": {
       "Modules\\Core\\": "src/"
@@ -36,6 +36,7 @@
         "Modules\\Core\\Providers\\AuthServiceProvider",
         "Modules\\Core\\Providers\\CustomerServiceProvider",
         "Modules\\Core\\Providers\\LocalizationServiceProvider",
+        "Modules\\Core\\Providers\\ProductServiceProvider",
         "Modules\\Core\\Providers\\ReviewServiceProvider"
       ]
     }

config/core.php

@@ -16,4 +16,23 @@ return [
 
     'auto_create_customer_for_user' => true,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Product Option Types
+    |--------------------------------------------------------------------------
+    |
+    | Enabled `Modules\Core\Product\Contracts\ProductOptionTypeInterface`
+    | implementations, describing what structured data a ProductOption's
+    | values carry in their `meta` jsonb column, and how an admin edits it.
+    | An admin picks one per ProductOption from a dropdown built from this
+    | list (stored in ProductOption::meta, not tied to the option's handle) —
+    | a ProductOption with none selected has no described meta behavior,
+    | plain name/position only.
+    |
+    | \App\ProductOptions\ColorOptionType::class,
+    |
+    */
+
+    'product_option_types' => [],
+
 ];

docs/localization.md

@@ -50,7 +50,7 @@ fine — just keep admin/Livewire/webhook routes registered outside of it (as th
 
 ## Behavior
 
-`Modules\Core\Localization\LocaleMiddleware`:
+`Modules\Core\Localization\Middleware\LocaleMiddleware`:
 
 1. Reads the first path segment (`request()->segment(1)`).
 2. Matches it against `Lunar\Models\Language::code`.
@@ -68,7 +68,7 @@ and invalidated automatically. Adding, editing, or removing a language via the F
 
 ### How invalidation is wired (event-driven, not the observer itself)
 
-`Modules\Core\Localization\LanguageCacheObserver` observes `Lunar\Models\Language`'s
+`Modules\Core\Localization\Observers\LanguageCacheObserver` observes `Lunar\Models\Language`'s
 `created`/`updated`/`deleted` Eloquent events, but it's a thin trigger only — it doesn't do any
 invalidation work itself. It dispatches one of three events from
 `Modules\Core\Localization\Events` (`LanguageCreated`, `LanguageUpdated` — carrying the old
@@ -105,6 +105,33 @@ $language = $request->attributes->get('language');   // Lunar\Models\Language in
 
 Use `$language->id` when querying Lunar's translatable content (e.g. `Url::where('language_id', ...)`).
 
+### Shared view data — language switcher and `hreflang` tags
+
+The middleware also shares two variables with every view, via `View::share()`, so a layout's
+language switcher or `hreflang` tags don't have to recompute the language list themselves:
+
+```blade
+{{-- current locale --}}
+{{ $currentLocale }}   {{-- e.g. "el" --}}
+
+{{-- every OTHER configured language, each with its own URL for the current page --}}
+@foreach ($altLocales as $altLocale)
+    <a href="{{ $altLocale['url'] }}" hreflang="{{ $altLocale['code'] }}">{{ $altLocale['name'] }}</a>
+@endforeach
+```
+
+`$altLocales` is a **collection**, not a single value — deliberately, so it scales to any number
+of configured languages rather than assuming exactly two. Each entry is a plain array:
+
+| Key | Description |
+|---|---|
+| `code` | The language's `Lunar\Models\Language::code` (e.g. `en`) |
+| `name` | The language's display name |
+| `url` | The **current route**, re-generated with that language's code — via `route($routeName, [...])` when the current request matched a named route, or a bare `/{code}` fallback otherwise |
+
+A 3+ language store gets one `$altLocales` entry per additional language automatically — nothing
+about this shape assumes or special-cases a two-language store.
+
 ---
 
 ## Single-language shops
@@ -151,6 +178,24 @@ namespaced groups so nothing collides. `__()` resolves the translation for whate
 `App::getLocale()` currently is, which `LocaleMiddleware` already sets per-request (see
 "Behavior" above) — no extra wiring needed between the two systems.
 
+### Fallback locale follows the store's default language, not `config('app.fallback_locale')`
+
+`spatie/laravel-translation-loader`'s stock `LanguageLine::getTranslation()` falls back to
+`config('app.fallback_locale')` — a static `.env` value — when a key has no text for the current
+locale. That's a second, disconnected "default language" concept: an admin changing the default
+language via the Filament **Languages** resource has no effect on it, so an untranslated label
+could silently fall back to the wrong language.
+
+`Modules\Core\Localization\Models\LanguageLine` overrides `getTranslation()` to fall back to
+`LanguageCache::defaultLocale()` instead — the same `languages.default` flag `LocaleMiddleware`
+already treats as the single source of truth. It's swapped in via
+`config('translation-loader.model')` (the package's own documented extension point for
+"any model that extends `LanguageLine`"), set in `LocalizationServiceProvider::register()` so it
+wins regardless of provider boot order (Laravel's `mergeConfigFrom()` only fills in config keys
+not already set, so an explicit `register()`-time set always beats the package's own default).
+No consuming app configuration needed — this is automatic once `LocalizationServiceProvider` is
+registered.
+
 ### Seeding
 
 A starter set of common e-shop labels (`nav.*`, `cart.*`, `product.*`, `auth.*`, `search.*`,
@@ -168,13 +213,13 @@ a third language automatically adds a third input, no resource changes needed.
 
 ### `TranslationService` — writes go through here, not the model directly
 
-`Modules\Core\Localization\TranslationService` wraps create/update/delete on `LanguageLine` and
+`Modules\Core\Localization\Services\TranslationService` wraps create/update/delete on `LanguageLine` and
 dispatches a domain event after each write, following this project's standard event-driven
 pattern (see `modules.md`'s "Splitting Service Providers" / event-listener convention —
 the same shape as `Modules\Core\Auth\Events\UserCreated`):
 
 ```php
-use Modules\Core\Localization\TranslationService;
+use Modules\Core\Localization\Services\TranslationService;
 
 app(TranslationService::class)->create('storefront', 'nav.wishlist', [
     'en' => 'Wishlist',

docs/lunar.md

@@ -1206,6 +1206,6 @@ Real bugs/traps hit while building against Lunar in this package — not obvious
 - **`ProductOption.handle` must be unique and non-null if a product has more than one option.** Lunar's Filament variant-switcher widget does `SelectFilter::make($option->handle)` per option — two options with a `null`/matching handle throws "Filter must have a unique name" as a 500 when opening that product's variant pricing page. Always derive a slug and check uniqueness.
 - **`Attribute.position` is per-group, and the panel sorts by it.** Hardcoding `position => 1` for multiple new attributes in the same group makes their order undefined/collide with existing attributes at position 1. Compute `max('position') + 1` per group instead.
 - **Currency `decimal_places` isn't always 2.** A seeded/demo currency can have the wrong value (seen: EUR seeded with `decimal_places = 1`), which silently corrupts every price display (`€16.50` renders as `165`). If prices look wrong by a factor of 10, check the currency row before assuming the price-writing code is broken.
-- **`Builder::paginateRaw()`'s `items()` is not a hit list on the Meilisearch driver.** It contains the *entire* raw response (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`) as one associative array. Treating `$paginator->items()` as a plain list (e.g. `collect($paginator->items())->values()`) silently produces 7 elements — the real hits array happens to land first, the rest are stray scalars from the other response keys — no error, just corrupted data. Pull `$paginator->items()['hits']` explicitly. `total()`/`perPage()`/`currentPage()`/`lastPage()` on the paginator are unaffected. See `Modules\Core\Catalog\ProductService` / `docs/product-listing.md`.
+- **`Builder::paginateRaw()`'s `items()` is not a hit list on the Meilisearch driver.** It contains the *entire* raw response (`hits`, `query`, `processingTimeMs`, `hitsPerPage`, `page`, `totalPages`, `totalHits`) as one associative array. Treating `$paginator->items()` as a plain list (e.g. `collect($paginator->items())->values()`) silently produces 7 elements — the real hits array happens to land first, the rest are stray scalars from the other response keys — no error, just corrupted data. Pull `$paginator->items()['hits']` explicitly. `total()`/`perPage()`/`currentPage()`/`lastPage()` on the paginator are unaffected. See `Modules\Core\Product\Services\ProductService` / `docs/product-listing.md`.
-- **`ProductOption`/`ProductOptionValue::$name` is not `attribute_data` — `translateAttribute('name')` silently returns null for them.** Unlike `Product`/`Collection`/`Brand`, their translated `name` is a plain locale-keyed array cast (`AsArrayObject`) directly on the column, not stored in `attribute_data`. `HasTranslations::translateAttribute()` only reads `attribute_data`, so calling it on these two models compiles fine and returns `null` with no error — read the array directly instead (`$value->name[$locale] ?? ...`). See `Modules\Core\Search\ProductIndexer::translatedName()`.
+- **`ProductOption`/`ProductOptionValue::$name` is not `attribute_data` — `translateAttribute('name')` silently returns null for them.** Unlike `Product`/`Collection`/`Brand`, their translated `name` is a plain locale-keyed array cast (`AsArrayObject`) directly on the column, not stored in `attribute_data`. `HasTranslations::translateAttribute()` only reads `attribute_data`, so calling it on these two models compiles fine and returns `null` with no error — read the array directly instead (`$value->name[$locale] ?? ...`). See `Modules\Core\Product\Services\ProductIndexer::translatedName()`.
 - **A running `queue:work` process does not pick up an edited/newly-added Scout indexer class.** It loads PHP classes once at boot and keeps them for the process's lifetime. Symptoms: reindexing commands succeed with no errors, calling `toSearchableArray()` directly (e.g. via `artisan tinker`, which always boots fresh) returns the new fields correctly, but documents written via `$model->searchable()` through the live queue are still missing them. Restart the queue worker after deploying an indexer change — no code fix needed.

docs/product-listing.md

@@ -1,10 +1,10 @@
 # Product Listing
 
-`Modules\Core\Catalog\ProductService` provides catalog browsing/filtering AND single-product
+`Modules\Core\Product\Services\ProductService` provides catalog browsing/filtering AND single-product
 lookup for a storefront — `list()`, `getById()`, `getBySlug()` — all reading directly from the
 Meilisearch index rather than the database. One data source for everything this service does.
 
-This is separate from `Modules\Core\Search\ProductSearchService` (see `product-search.md`), which
+This is separate from `Modules\Core\Product\Services\ProductSearchService` (see `product-search.md`), which
 handles free-text query search. `ProductService` is for browsing/lookup without a search term.
 
 ---
@@ -14,7 +14,7 @@ handles free-text query search. `ProductService` is for browsing/lookup without
 Every method here reads Meilisearch documents directly and returns plain arrays — never Scout's
 `->get()`, which would re-hydrate Eloquent models from the database. This means the index has to
 carry everything a detail page needs (variants, prices, options, media, reviews — see below), not
-just the trimmed fields a listing page needs. `Modules\Core\Search\ProductIndexer` is built to
+just the trimmed fields a listing page needs. `Modules\Core\Product\Services\ProductIndexer` is built to
 carry that full shape.
 
 ---
@@ -22,26 +22,34 @@ carry that full shape.
 ## Usage
 
 ```php
-use Modules\Core\Catalog\ProductFilters;
+use Modules\Core\Product\DTOs\ProductFilters;
-use Modules\Core\Catalog\ProductService;
+use Modules\Core\Product\Services\ProductService;
+use Modules\Core\Product\Enums\ProductSort;
 
 $service = app(ProductService::class);
 
-// List everything, paginated
+// List everything, paginated — returns a real Illuminate\Pagination\LengthAwarePaginator,
-$result = $service->list(perPage: 24, page: 1);
+// built from the localized Meilisearch hits (not Scout's own paginateRaw() result — see
+// "Meilisearch driver quirk" below), so it behaves like any other Laravel paginator.
+$products = $service->list(perPage: 24, page: 1);
 
 // Filter by collection, brand, and/or price range
-$result = $service->list(
+$products = $service->list(
     filters: new ProductFilters(collectionId: 17, minPrice: 10.0, maxPrice: 50.0),
     perPage: 24,
     page: 1,
 );
 
-$result['data'];               // array of Meilisearch documents (plain arrays, not models)
+// Sort — cheapest/priciest first, or newest first. Omit for Meilisearch's default
-$result['meta']['total'];
+// relevance ordering (irrelevant here since the query is always empty).
-$result['meta']['per_page'];
+$products = $service->list(perPage: 24, page: 1, sort: ProductSort::PriceAsc);
-$result['meta']['current_page'];
+
-$result['meta']['last_page'];
+$products->items();            // array of Meilisearch documents (plain arrays, not models)
+$products->total();
+$products->perPage();
+$products->currentPage();
+$products->lastPage();
+$products->links();            // in a Blade view — renders pagination links as usual
 
 // Single product, by primary key
 $product = $service->getById(367);   // array, or null if not found
@@ -54,11 +62,11 @@ All `ProductFilters` fields are optional; only the ones set are added to the Mei
 
 ---
 
-## Fields this depends on: `Modules\Core\Search\ProductIndexer`
+## Fields this depends on: `Modules\Core\Product\Services\ProductIndexer`
 
 Lunar's own `Lunar\Search\ProductIndexer` only carries listing-grade fields (name, description,
 status, brand, a single thumbnail, skus) and marks just `__soft_deleted`, `skus`, `status` as
-filterable. `Modules\Core\Search\ProductIndexer` extends it to add everything `ProductService`
+filterable. `Modules\Core\Product\Services\ProductIndexer` extends it to add everything `ProductService`
 needs, listing and detail alike:
 
 | Field | Source | Notes |
@@ -74,9 +82,8 @@ needs, listing and detail alike:
 | `variants` | `$product->variants` | Per variant: `id`, `sku`, `stock`, `purchasable`, `options` (option/value names, in the current locale), `prices` (per currency/customer group), `media` (variant-specific images). |
 | `reviews`, `review_count`, `average_rating` | `Modules\Core\Review\Models\ProductReview` | See "Reviews" below. |
 
-`description` and other translated attributes are indexed as-is, including any HTML markup
+`name`/`description` (and any other `TranslatedText` attribute) are indexed per-locale — see
-(e.g. from a Shopify `Body (HTML)` import) — **not stripped**. Any view rendering a description
+"Locale resolution" below for how `ProductService` resolves them down to one value per request.
-sourced from `ProductService`'s results must treat it as trusted HTML.
 
 **`ProductOption`/`ProductOptionValue` names need a different translation accessor.** Unlike
 `Product`/`Collection`/`Brand`, their `name` is a plain locale-keyed array cast, not
@@ -85,6 +92,33 @@ indexer's `translatedName()` reads the array directly instead. See `docs/lunar.m
 
 ---
 
+## Locale resolution: `name`, `description`, and any other translated attribute
+
+Lunar's base `ScoutIndexer` explodes every `TranslatedText` attribute into one `{handle}_{locale}`
+field per store language at index time (`name_el`, `name_en`, `description_el`, ... — and the same
+for any custom translated attribute a store adds, e.g. `seo_title`/`seo_description`). Every raw
+document in Meilisearch carries all of them side by side, since a document is written once but
+read across many different-locale requests.
+
+`ProductService` resolves these back down to a single value per request. For every result it
+returns (`list()`'s items, `getById()`, `getBySlug()`), it:
+
+1. Reads which `Product` attributes are `TranslatedText` from `Lunar\Base\AttributeManifest` — the
+   same source Lunar's own indexer reads — rather than a hardcoded `['name', 'description']` list,
+   so a store's own custom translated attributes are picked up automatically with no change here.
+2. For each one, resolves `{handle}_{currentLocale}`, falling back to `{handle}_{storeDefaultLocale}`
+   (`LanguageCache::defaultLocale()`) if the current locale has no translation — e.g. a product with
+   no English copy yet still shows its Greek name on `/en/` rather than rendering blank.
+3. Assigns the result to a plain `{handle}` key and **strips every raw `{handle}_{locale}` key** —
+   callers only ever see `$product['name']`/`$product['seo_title']`/etc., never the per-locale
+   fields the index actually stores.
+
+`description` and other translated attributes are otherwise indexed as-is, including any HTML
+markup (e.g. from a Shopify `Body (HTML)` import) — **not stripped**. Any view rendering a
+description sourced from `ProductService`'s results must treat it as trusted HTML.
+
+---
+
 ## Reviews
 
 `Modules\Core\Review\Models\ProductReview` (`product_reviews` table) is indexed per-product as
@@ -113,13 +147,28 @@ variants don't.
 
 ---
 
+## Sorting
+
+`ProductSort` (`Modules\Core\Product\Enums\ProductSort`) is a fixed enum of supported sort orders —
+`PriceAsc`, `PriceDesc`, `Newest` — each mapping to a Meilisearch `sort` clause against a field
+`Modules\Core\Product\Services\ProductIndexer::getSortableFields()` marks sortable (`price`, plus
+`created_at`/`updated_at`/`skus`/`status` inherited from Lunar's base indexer). Adding a new
+`ProductSort` case requires adding the matching field to `getSortableFields()` and re-syncing (see
+below) — sortable attributes are index settings, not computed per-query, same as filterable ones.
+
+Omitting `sort` leaves Meilisearch's default ordering, which is meaningless here since `list()`
+always searches with an empty query string (`Product::search('')`) — there's no relevance score to
+rank by, so results come back in whatever order the index returns them absent an explicit sort.
+
+---
+
 ## Registering the indexer
 
 Not automatic — an app opts in via its own `config/lunar/search.php`:
 
 ```php
 'indexers' => [
-    Lunar\Models\Product::class => Modules\Core\Search\ProductIndexer::class,
+    Lunar\Models\Product::class => Modules\Core\Product\Services\ProductIndexer::class,
     // ...other model indexers unchanged
 ],
 ```

docs/product-options.md

@@ -0,0 +1,105 @@
+# Product Option Types
+
+Lunar's `ProductOption`/`ProductOptionValue` are generic by design — a "Color" option
+and a "Size" option are both just a handle, a translated name, and a list of values.
+Each `ProductOptionValue` carries a free-form `meta` jsonb column, but nothing in
+Lunar's own admin UI exposes it — there's no way for an admin to, say, attach a hex
+code to a "Red" value without editing the database directly.
+
+`Modules\Core\Product\Contracts\ProductOptionTypeInterface` describes how a category
+of option behaves — what structured data its values carry in `meta`, and how an
+admin edits that data — without introducing a new model. `ProductOption`/
+`ProductOptionValue` stay exactly as Lunar defines them.
+
+---
+
+## Registering a type
+
+A shop enables a type class in `config/core.php`:
+
+```php
+// config/core.php
+'product_option_types' => [
+    \App\ProductOptions\ColorOptionType::class,
+],
+```
+
+This is a plain list, **not** keyed by `ProductOption::handle` — a shop's own handle
+naming (transliterated Greek, legacy import slugs, whatever an admin happened to type
+when creating the option) shouldn't have to match a type's key. Instead, an admin
+picks a type per-option from a dropdown on the `ProductOption` edit form itself (see
+below); the choice is stored in `ProductOption::meta['option_type']`, not inferred
+from anything else.
+
+A `ProductOption` with no type selected behaves exactly as stock Lunar does — plain
+name/position, no extra meta form.
+
+---
+
+## Writing a type
+
+```php
+namespace App\ProductOptions;
+
+use Filament\Forms\Components\ColorPicker;
+use Modules\Core\Product\Contracts\ProductOptionTypeInterface;
+
+class ColorOptionType implements ProductOptionTypeInterface
+{
+    public static function getKey(): string
+    {
+        return 'color';
+    }
+
+    public function getMetaForm(): array
+    {
+        return [
+            ColorPicker::make('meta.hex')
+                ->label('Color')
+                ->required(),
+        ];
+    }
+}
+```
+
+`getMetaForm()` returns Filament form components, keyed under `meta.*` dot notation
+— the path they save to on `ProductOptionValue::meta` (cast as `AsArrayObject`, a
+plain jsonb column). `getKey()` is the identifier used in the admin's "Option Type"
+dropdown and in `ProductOption::meta['option_type']` — it has no relationship to the
+`ProductOption::handle`.
+
+A reference implementation ships at `Modules\Core\Product\OptionTypes\ColorOptionType`
+— not auto-registered, since registration is always an explicit shop decision.
+
+---
+
+## How it's wired into the admin UI
+
+`Modules\Core\Product\Services\ProductOptionTypeManager`:
+- `all(): Collection<string, ProductOptionTypeInterface>` — every enabled type,
+  keyed by `getKey()`.
+- `resolve(?string $key): ?ProductOptionTypeInterface` — looks up one by key (or
+  `null` if no key / not found).
+
+Two extensions hook into Lunar's admin via its extension system
+(`LunarPanel::extensions([...])`, registered in `CorePlugin`) — no forking of Lunar's
+classes needed:
+
+- `Modules\Core\Product\Filament\Extensions\ProductOptionResourceExtension` extends
+  `Lunar\Admin\Filament\Resources\ProductOptionResource`'s own form with a `Select`
+  (`meta.option_type`) listing every enabled type's key. Shown only when at least one
+  type is enabled.
+- `Modules\Core\Product\Filament\Extensions\ValuesRelationManagerExtension` extends
+  the "Values" tab's form. Its `extendForm()` reads
+  `$option->meta['option_type']` off the owning `ProductOption`, resolves it via
+  `ProductOptionTypeManager`, and appends `getMetaForm()`'s fields to the stock name
+  field. A `ProductOption` with no type selected gets the stock form unchanged.
+
+---
+
+## Reading the value back
+
+Storefront code reads `ProductOptionValue::meta` like any other jsonb column — e.g.
+`$value->meta['hex']` for a color swatch. `ProductOptionTypeManager` is an admin-side
+concern only (describing *how to edit* the meta); nothing requires the storefront to
+go through it to *read* the meta.

docs/product-search.md

@@ -1,6 +1,6 @@
 # Product Search
 
-`Modules\Core\Search\ProductSearchService` provides locale-aware full-text product search on
+`Modules\Core\Product\Services\ProductSearchService` provides locale-aware full-text product search on
 top of Laravel Scout + Meilisearch.
 
 ---
@@ -24,7 +24,7 @@ merges `$builder->options` directly into the search request).
 ## Usage
 
 ```php
-use Modules\Core\Search\ProductSearchService;
+use Modules\Core\Product\Services\ProductSearchService;
 
 $results = app(ProductSearchService::class)->search('running shoes');
 // or an explicit locale, bypassing App::getLocale():
@@ -36,7 +36,7 @@ Returns an `Illuminate\Database\Eloquent\Collection` of `Lunar\Models\Product`
 (`variants`, `brand`, `media`, etc.) are available on the results as normal.
 
 `$locale` defaults to `App::getLocale()` — already set correctly on every storefront request by
-`Modules\Core\Localization\LocaleMiddleware` (see `localization.md`), so callers in controllers
+`Modules\Core\Localization\Middleware\LocaleMiddleware` (see `localization.md`), so callers in controllers
 don't need to pass it explicitly.
 
 ---

src/Catalog/ProductService.php

@@ -1,126 +0,0 @@
-<?php
-
-namespace Modules\Core\Catalog;
-
-use Illuminate\Contracts\Pagination\LengthAwarePaginator;
-use Illuminate\Support\Collection;
-use Illuminate\Support\Facades\App;
-use Lunar\Models\Product;
-use Modules\Core\Localization\LocaleMiddleware;
-
-/**
- * Storefront product listing/filtering AND single-product lookup, all reading directly
- * from the Meilisearch index (Modules\Core\Search\ProductIndexer) - one data source, no
- * ->get() model hydration anywhere in this service. Callers get plain arrays of the
- * indexed document, not Eloquent models.
- *
- * Full-text query search lives separately in Modules\Core\Search\ProductSearchService;
- * this service is for browsing/filtering without a search term.
- */
-class ProductService
-{
-    /**
-     * @return array{data: array<int, array>, meta: array}
-     */
-    public function list(?ProductFilters $filters = null, int $perPage = 24, int $page = 1): array
-    {
-        $paginator = Product::search('')
-            ->options([
-                'filter' => $this->buildFilter($filters),
-            ])
-            ->paginateRaw(perPage: $perPage, page: $page);
-
-        return [
-            'data' => collect($this->hitsFrom($paginator))
-                ->map(fn (array $product) => $this->withLocalizedFields($product))
-                ->all(),
-            'meta' => [
-                'total' => $paginator->total(),
-                'per_page' => $paginator->perPage(),
-                'current_page' => $paginator->currentPage(),
-                'last_page' => $paginator->lastPage(),
-            ],
-        ];
-    }
-
-    /**
-     * Look up a single product by its URL slug (any locale - slugs are indexed across
-     * all languages, see Modules\Core\Search\ProductIndexer). Returns the full indexed
-     * product document, or null if no product has that slug.
-     */
-    public function getBySlug(string $slug): ?array
-    {
-        return $this->findOneWhere('slugs = "'.addcslashes($slug, '"\\').'"');
-    }
-
-    /**
-     * Look up a single product by its primary key. Returns the full indexed product
-     * document, or null if no product has that id.
-     */
-    public function getById(int $id): ?array
-    {
-        return $this->findOneWhere("id = \"{$id}\"");
-    }
-
-    private function findOneWhere(string $filter): ?array
-    {
-        $paginator = Product::search('')
-            ->options(['filter' => $filter])
-            ->paginateRaw(perPage: 1, page: 1);
-
-        $product = $this->hitsFrom($paginator)[0] ?? null;
-
-        return $product !== null ? $this->withLocalizedFields($product) : null;
-    }
-
-    /**
-     * Resolves the current-locale `name`/`description` from the indexer's
-     * per-locale `name_{locale}`/`description_{locale}` fields, falling back to
-     * the store's default language (Language::default, see
-     * LocaleMiddleware::defaultLocale()) when the current locale has no
-     * translation - e.g. a product with no English copy yet still shows its
-     * Greek name/description on /en/ rather than rendering blank.
-     *
-     * Deliberately not config('app.locale') - App::setLocale() overwrites that
-     * config value on every request, so by request time it's just whatever the
-     * current locale already is, not a stable fallback.
-     */
-    private function withLocalizedFields(array $product): array
-    {
-        $locale = App::getLocale();
-        $fallbackLocale = LocaleMiddleware::defaultLocale();
-
-        $product['name'] = $product['name_'.$locale] ?? $product['name_'.$fallbackLocale] ?? null;
-        $product['description'] = $product['description_'.$locale] ?? $product['description_'.$fallbackLocale] ?? null;
-
-        return $product;
-    }
-
-    /**
-     * For the Meilisearch driver, Scout's paginateRaw() puts the whole raw response
-     * (hits, query, processingTimeMs, ...) in items(), not a plain list of hits - the
-     * actual documents are under the 'hits' key.
-     */
-    private function hitsFrom(LengthAwarePaginator $paginator): array
-    {
-        $rawResponse = $paginator->items();
-
-        return collect($rawResponse['hits'] ?? [])->values()->all();
-    }
-
-    private function buildFilter(?ProductFilters $filters): ?string
-    {
-        if ($filters === null) {
-            return null;
-        }
-
-        $clauses = Collection::make([
-            $filters->collectionId !== null ? "collections = \"{$filters->collectionId}\"" : null,
-            $filters->brand !== null ? 'brand = "'.addcslashes($filters->brand, '"\\').'"' : null,
-            $filters->minPrice !== null ? "price >= {$filters->minPrice}" : null,
-            $filters->maxPrice !== null ? "price <= {$filters->maxPrice}" : null,
-        ])->filter();
-
-        return $clauses->isEmpty() ? null : $clauses->join(' AND ');
-    }
-}

src/CorePlugin.php

@@ -6,6 +6,8 @@ use Filament\Contracts\Plugin;
 use Filament\Panel;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Support\Facades\Mail;
+use Lunar\Admin\Filament\Resources\ProductOptionResource;
+use Lunar\Admin\Filament\Resources\ProductOptionResource\RelationManagers\ValuesRelationManager;
 use Lunar\Admin\Filament\Resources\ProductResource;
 use Lunar\Admin\Filament\Resources\StaffResource;
 use Lunar\Admin\Models\Staff as LunarStaff;
@@ -16,6 +18,8 @@ use Modules\Core\Auth\Extensions\StaffResourceExtension;
 use Modules\Core\Auth\Filament\Pages\Login;
 use Modules\Core\Auth\Mail\InviteMail;
 use Modules\Core\Localization\Filament\Resources\LanguageLineResource;
+use Modules\Core\Product\Filament\Extensions\ProductOptionResourceExtension;
+use Modules\Core\Product\Filament\Extensions\ValuesRelationManagerExtension;
 use Modules\Core\Review\Extensions\ProductResourceExtension;
 use Modules\Core\Review\Models\ProductReview;
 
@@ -41,6 +45,8 @@ class CorePlugin implements Plugin
         LunarPanel::extensions([
             StaffResource::class => StaffResourceExtension::class,
             ProductResource::class => ProductResourceExtension::class,
+            ProductOptionResource::class => ProductOptionResourceExtension::class,
+            ValuesRelationManager::class => ValuesRelationManagerExtension::class,
         ]);
 
         Product::macro('reviews', function (): HasMany {

src/Localization/Filament/Resources/LanguageLineResource/Pages/CreateLanguageLine.php

@@ -5,7 +5,7 @@ namespace Modules\Core\Localization\Filament\Resources\LanguageLineResource\Page
 use Filament\Resources\Pages\CreateRecord;
 use Illuminate\Database\Eloquent\Model;
 use Modules\Core\Localization\Filament\Resources\LanguageLineResource;
-use Modules\Core\Localization\TranslationService;
+use Modules\Core\Localization\Services\TranslationService;
 
 class CreateLanguageLine extends CreateRecord
 {

src/Localization/Filament/Resources/LanguageLineResource/Pages/EditLanguageLine.php

@@ -7,7 +7,7 @@ use Filament\Actions\Action;
 use Filament\Resources\Pages\EditRecord;
 use Illuminate\Database\Eloquent\Model;
 use Modules\Core\Localization\Filament\Resources\LanguageLineResource;
-use Modules\Core\Localization\TranslationService;
+use Modules\Core\Localization\Services\TranslationService;
 use Spatie\TranslationLoader\LanguageLine;
 
 class EditLanguageLine extends EditRecord

src/Localization/Listeners/FlushLanguageCache.php

@@ -5,12 +5,14 @@ namespace Modules\Core\Localization\Listeners;
 use Modules\Core\Localization\Events\LanguageCreated;
 use Modules\Core\Localization\Events\LanguageDeleted;
 use Modules\Core\Localization\Events\LanguageUpdated;
-use Modules\Core\Localization\LocaleMiddleware;
+use Modules\Core\Localization\Services\LanguageCache;
 
 class FlushLanguageCache
 {
+    public function __construct(private readonly LanguageCache $languages) {}
+
     public function handle(LanguageCreated|LanguageUpdated|LanguageDeleted $event): void
     {
-        LocaleMiddleware::forgetLanguagesCache();
+        $this->languages->forget();
     }
 }

src/Localization/Middleware/LocaleMiddleware.php

@@ -1,24 +1,24 @@
 <?php
 
-namespace Modules\Core\Localization;
+namespace Modules\Core\Localization\Middleware;
 
 use Closure;
 use Illuminate\Http\Request;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\App;
-use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\URL;
 use Illuminate\Support\Facades\View;
 use Lunar\Models\Language;
+use Modules\Core\Localization\Services\LanguageCache;
 use Symfony\Component\HttpFoundation\Response;
 
 class LocaleMiddleware
 {
-    private const CACHE_KEY = 'core.localization.languages';
+    public function __construct(private readonly LanguageCache $languages) {}
 
     public function handle(Request $request, Closure $next): Response
     {
-        $languages = $this->availableLanguages();
+        $languages = $this->languages->all();
 
         if ($languages->isEmpty()) {
             return $next($request);
@@ -45,41 +45,37 @@ class LocaleMiddleware
         return $next($request);
     }
 
-    public static function forgetLanguagesCache(): void
-    {
-        Cache::forget(self::CACHE_KEY);
-    }
-
     /**
-     * The store's default language code (e.g. 'el') - the fixed fallback other
+     * Shares the current locale and every OTHER available locale (each with its
-     * locale-aware code (Modules\Core\Catalog\ProductService) should use, as
+     * own URL for the current page) with all views, so the header language
-     * opposed to config('app.locale') which App::setLocale() mutates per
+     * switcher and layout hreflang tags don't have to recompute it.
-     * request and so can't serve as a stable fallback.
+     *
-     */
+     * `altLocales` is a collection, not a single value — firstWhere('code', '!=',
-    public static function defaultLocale(): ?string
+     * ...) would only ever surface one alternate, which happens to look correct
-    {
+     * with exactly 2 configured languages (there's only one "other" to find) but
-        return (new self)->availableLanguages()->firstWhere('default', true)?->code;
+     * silently drops every locale past the first for a 3+ language store, with no
-    }
+     * error, just fewer switcher options than actually configured. A view iterates
-
+     * `$altLocales` to render as many links/dropdown entries as there are
-    /**
+     * alternates, whether that's 1 or 10.
-     * Shares the current/alternate locale (and the alternate's URL) with all
-     * views, so the header language switcher and layout hreflang tags don't
-     * have to recompute it.
      */
     private function shareLocaleViewData(Request $request, Language $language, Collection $languages): void
     {
-        $altLanguage = $languages->firstWhere('code', '!=', $language->code);
         $route = $request->route();
         $routeName = $route?->getName();
 
+        $altLocales = $languages
+            ->reject(fn (Language $other) => $other->code === $language->code)
+            ->map(fn (Language $other) => [
+                'code' => $other->code,
+                'name' => $other->name,
+                'url' => $routeName
+                    ? route($routeName, array_merge($route->parameters(), ['locale' => $other->code]))
+                    : url('/'.$other->code),
+            ])
+            ->values();
+
         View::share('currentLocale', $language->code);
-        View::share('altLocale', $altLanguage?->code);
+        View::share('altLocales', $altLocales);
-        View::share(
-            'altLocaleUrl',
-            $altLanguage && $routeName
-                ? route($routeName, array_merge($route->parameters(), ['locale' => $altLanguage->code]))
-                : ($altLanguage ? url('/'.$altLanguage->code) : null),
-        );
     }
 
     private function redirectToLocalizedUrl(Request $request, Collection $languages): Response
@@ -108,12 +104,4 @@ class LocaleMiddleware
         return $languages->firstWhere('default', true)?->code
             ?? $languages->first()->code;
     }
-
-    private function availableLanguages(): Collection
-    {
-        return Cache::rememberForever(
-            self::CACHE_KEY,
-            fn () => Language::query()->get(['id', 'code', 'name', 'default']),
-        );
-    }
 }

src/Localization/Models/LanguageLine.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Modules\Core\Localization\Models;
+
+use Modules\Core\Localization\Services\LanguageCache;
+use Spatie\TranslationLoader\LanguageLine as BaseLanguageLine;
+
+/**
+ * Overrides the base package's locale fallback (config('app.fallback_locale'), a
+ * static .env value) with the store's actual default language — Lunar's
+ * `languages.default` flag, the same source LocaleMiddleware/LanguageCache already
+ * treat as the single source of truth for "this store's default language".
+ *
+ * Without this, changing the default language via the Filament Languages resource
+ * has no effect on which locale an untranslated storefront label falls back to —
+ * two disconnected "default locale" concepts silently drifting apart. Swapped in
+ * via config('translation-loader.model') (see LocalizationServiceProvider), the
+ * package's own documented extension point for this.
+ */
+class LanguageLine extends BaseLanguageLine
+{
+    public function getTranslation(string $locale): ?string
+    {
+        if (isset($this->text[$locale])) {
+            return $this->text[$locale];
+        }
+
+        $fallback = app(LanguageCache::class)->defaultLocale();
+
+        return $fallback !== null ? ($this->text[$fallback] ?? null) : null;
+    }
+}

src/Localization/Observers/LanguageCacheObserver.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Modules\Core\Localization;
+namespace Modules\Core\Localization\Observers;
 
 use Illuminate\Support\Facades\Event;
 use Lunar\Models\Language;

src/Localization/Services/LanguageCache.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Modules\Core\Localization\Services;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Cache;
+use Lunar\Models\Language;
+
+/**
+ * Cached read layer over Lunar's `languages` table — the single source both
+ * Modules\Core\Localization\Middleware\LocaleMiddleware (request-time locale resolution) and
+ * any other locale-aware code (e.g. Modules\Core\Product\Services\ProductService) read
+ * from, so the language list is fetched once per cache lifetime rather than once
+ * per caller. Cached forever, invalidated via forget() by
+ * Modules\Core\Localization\Listeners\FlushLanguageCache on
+ * LanguageCreated/LanguageUpdated/LanguageDeleted.
+ */
+class LanguageCache
+{
+    private const CACHE_KEY = 'core.localization.languages';
+
+    public function all(): Collection
+    {
+        return Cache::rememberForever(
+            self::CACHE_KEY,
+            fn () => Language::query()->get(['id', 'code', 'name', 'default']),
+        );
+    }
+
+    /**
+     * The store's default language code (e.g. 'el') - the fixed fallback other
+     * locale-aware code should use, as opposed to config('app.locale') which
+     * App::setLocale() mutates per request and so can't serve as a stable
+     * fallback.
+     */
+    public function defaultLocale(): ?string
+    {
+        return $this->all()->firstWhere('default', true)?->code;
+    }
+
+    /**
+     * Every configured store locale code (e.g. ['el', 'en']) - for code that needs
+     * to enumerate all locales a TranslatedText attribute was indexed under (see
+     * Modules\Core\Product\Services\ProductService::withLocalizedFields()), rather than
+     * hardcoding locale codes.
+     *
+     * @return array<int, string>
+     */
+    public function availableLocales(): array
+    {
+        return $this->all()->pluck('code')->all();
+    }
+
+    public function forget(): void
+    {
+        Cache::forget(self::CACHE_KEY);
+    }
+}

src/Localization/Services/TranslationReader.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Modules\Core\Localization;
+namespace Modules\Core\Localization\Services;
 
 use Illuminate\Support\Facades\App;
 use Spatie\TranslationLoader\LanguageLine;

src/Localization/Services/TranslationService.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Modules\Core\Localization;
+namespace Modules\Core\Localization\Services;
 
 use Illuminate\Support\Facades\Event;
 use Modules\Core\Localization\Events\TranslationCreated;

src/MigrateImport/JudgeMe/Resolvers/ProductResolver.php

@@ -7,13 +7,23 @@ use Lunar\Models\Url;
 
 class ProductResolver
 {
+    /**
+     * A slug can have more than one `lunar_urls` row pointing at it across import
+     * batches — e.g. a product soft-deleted and re-imported leaves its old URL row
+     * behind, still matching the same slug. Picking "whichever Url row matches
+     * first" (as a plain Url::where('slug', ...)->first() would) can resolve to a
+     * soft-deleted product, silently failing every downstream write for that
+     * product (e.g. JudgeMeExportImporter logging "no product found" for a handle
+     * that, in isolation, clearly exists). Join against `lunar_products` directly
+     * so only a URL pointing at a live (non-deleted) product resolves.
+     */
     public function resolve(string $handle): ?Product
     {
-        $url = Url::query()
+        return Product::query()
-            ->where('slug', $handle)
+            ->join('lunar_urls', 'lunar_urls.element_id', '=', 'lunar_products.id')
-            ->where('element_type', (new Product)->getMorphClass())
+            ->where('lunar_urls.slug', $handle)
+            ->where('lunar_urls.element_type', (new Product)->getMorphClass())
+            ->select('lunar_products.*')
             ->first();
-
-        return $url?->element;
     }
 }

src/Product/Contracts/ProductOptionTypeInterface.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Modules\Core\Product\Contracts;
+
+use Filament\Forms\Components\Component;
+
+/**
+ * A Product Option Type describes how a category of Lunar `ProductOption` (e.g.
+ * "Color", "Size", "Material") behaves — namely, what structured data its values
+ * carry in their free-form `meta` jsonb column, and how an admin edits that data.
+ *
+ * `ProductOption`/`ProductOptionValue` themselves stay exactly as Lunar defines
+ * them — this is not a new model. `ProductOptionTypeManager` maps a
+ * `ProductOption::handle` to the type describing it (via `config('core.product_option_types')`,
+ * typed explicitly by the admin), so adding a new kind of option is a single new
+ * class, not scattered per-option special-casing across the admin UI or storefront.
+ */
+interface ProductOptionTypeInterface
+{
+    /**
+     * Matches the ProductOption::handle this type describes (e.g. 'color', 'size').
+     */
+    public static function getKey(): string;
+
+    /**
+     * Filament form components for editing a ProductOptionValue's `meta` under this
+     * option type — e.g. Color returns a color picker for `meta.hex`, Size returns a
+     * numeric input for `meta.sort_value`. Field names should be dot-notation under
+     * `meta` (e.g. `meta.hex`), matching where ValuesRelationManagerExtension saves them.
+     *
+     * @return array<Component>
+     */
+    public function getMetaForm(): array;
+}

src/Product/DTOs/ProductFilters.php

@@ -1,13 +1,13 @@
 <?php
 
-namespace Modules\Core\Catalog;
+namespace Modules\Core\Product\DTOs;
 
 /**
  * Filter input for ProductService::list(). All fields are optional — omitted
  * filters are simply not added to the Meilisearch query. Values are matched
- * against Modules\Core\Search\ProductIndexer's document fields, so filtering
+ * against Modules\Core\Product\Services\ProductIndexer's document fields, so
- * only works on stores where that indexer is registered and the index has
+ * filtering only works on stores where that indexer is registered and the index
- * been re-synced (see docs/product-listing.md).
+ * has been re-synced (see docs/product-listing.md).
  */
 class ProductFilters
 {

src/Product/Enums/ProductSort.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Modules\Core\Product\Enums;
+
+/**
+ * Sort options for ProductService::list(), each mapped to a Meilisearch `sort`
+ * clause against a field indexed as sortable by Modules\Core\Product\Services\
+ * ProductIndexer (see its getSortableFields()). Adding a case here requires the
+ * matching field to also be sortable in the index, re-synced via
+ * `php artisan lunar:meilisearch:setup`.
+ */
+enum ProductSort: string
+{
+    case PriceAsc = 'price_asc';
+    case PriceDesc = 'price_desc';
+    case Newest = 'newest';
+
+    public function toMeilisearchSort(): string
+    {
+        return match ($this) {
+            self::PriceAsc => 'price:asc',
+            self::PriceDesc => 'price:desc',
+            self::Newest => 'created_at:desc',
+        };
+    }
+}

src/Product/Filament/Extensions/ProductOptionResourceExtension.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Modules\Core\Product\Filament\Extensions;
+
+use Filament\Forms\Components\Select;
+use Filament\Forms\Form;
+use Illuminate\Support\Str;
+use Lunar\Admin\Support\Extending\ResourceExtension;
+use Modules\Core\Product\Services\ProductOptionTypeManager;
+
+/**
+ * Adds an "Option Type" dropdown to Lunar's own ProductOptionResource form, letting
+ * an admin pick which registered `ProductOptionTypeInterface` (if any) describes this
+ * option's values — e.g. "Color" — independent of the option's own `handle`. The
+ * selection is saved to `ProductOption::meta['option_type']`.
+ */
+class ProductOptionResourceExtension extends ResourceExtension
+{
+    public function extendForm(Form $form): Form
+    {
+        $options = app(ProductOptionTypeManager::class)->all()
+            ->keys()
+            ->mapWithKeys(fn (string $key) => [$key => Str::headline($key)])
+            ->all();
+
+        if ($options === []) {
+            return $form;
+        }
+
+        return $form->schema([
+            ...$form->getComponents(),
+            Select::make('meta.option_type')
+                ->label('Option Type')
+                ->options($options)
+                ->helperText('Controls which meta fields appear when editing this option\'s values.')
+                ->native(false),
+        ]);
+    }
+}

src/Product/Filament/Extensions/ValuesRelationManagerExtension.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Modules\Core\Product\Filament\Extensions;
+
+use Filament\Forms\Form;
+use Lunar\Admin\Support\Extending\RelationManagerExtension;
+use Lunar\Models\ProductOption;
+use Modules\Core\Product\Services\ProductOptionTypeManager;
+
+/**
+ * Appends the owning `ProductOption`'s registered `ProductOptionTypeInterface` meta
+ * form (if any) to Lunar's own ValuesRelationManager form, so e.g. a "color" option
+ * gets a hex-color picker for each value alongside the stock name field — without
+ * forking Lunar's relation manager.
+ */
+class ValuesRelationManagerExtension extends RelationManagerExtension
+{
+    public function extendForm(Form $form): Form
+    {
+        /** @var ProductOption $option */
+        $option = $this->caller->getOwnerRecord();
+
+        $type = app(ProductOptionTypeManager::class)->resolve($option->meta['option_type'] ?? null);
+
+        if ($type === null) {
+            return $form;
+        }
+
+        return $form->schema([
+            ...$form->getComponents(),
+            ...$type->getMetaForm(),
+        ]);
+    }
+}

src/Product/Observers/ProductOptionReindexObserver.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Modules\Core\Product\Observers;
+
+use Illuminate\Support\Facades\DB;
+use Lunar\Models\Product;
+use Lunar\Models\ProductOption;
+use Lunar\Models\ProductOptionValue;
+use Lunar\Models\ProductVariant;
+
+/**
+ * Keeps every product using a ProductOption/ProductOptionValue in sync with
+ * Meilisearch. ProductIndexer::mapVariant() embeds each option value's `meta`
+ * (e.g. a color's hex) directly into the product's indexed document — but saving
+ * the option or one of its values never fires the *product's* own save/update
+ * events, so without this, a changed option_type or a changed hex would only
+ * reach the index on that product's next unrelated reindex.
+ */
+class ProductOptionReindexObserver
+{
+    public function optionSaved(ProductOption $option): void
+    {
+        $this->reindexProductsForOption($option->id);
+    }
+
+    public function optionDeleted(ProductOption $option): void
+    {
+        $this->reindexProductsForOption($option->id);
+    }
+
+    public function valueSaved(ProductOptionValue $value): void
+    {
+        $this->reindexProductsForValues([$value->id]);
+    }
+
+    public function valueDeleted(ProductOptionValue $value): void
+    {
+        $this->reindexProductsForValues([$value->id]);
+    }
+
+    private function reindexProductsForOption(int $optionId): void
+    {
+        $valueIds = ProductOptionValue::where('product_option_id', $optionId)->pluck('id');
+
+        $this->reindexProductsForValues($valueIds->all());
+    }
+
+    private function reindexProductsForValues(array $valueIds): void
+    {
+        if ($valueIds === []) {
+            return;
+        }
+
+        $prefix = config('lunar.database.table_prefix');
+
+        $variantIds = DB::table("{$prefix}product_option_value_product_variant")
+            ->whereIn('value_id', $valueIds)
+            ->pluck('variant_id');
+
+        if ($variantIds->isEmpty()) {
+            return;
+        }
+
+        $productIds = ProductVariant::whereIn('id', $variantIds)->pluck('product_id')->unique();
+
+        Product::whereIn('id', $productIds)->get()->each->searchable();
+    }
+}

src/Product/OptionTypes/ColorOptionType.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Modules\Core\Product\OptionTypes;
+
+use Filament\Forms\Components\ColorPicker;
+use Modules\Core\Product\Contracts\ProductOptionTypeInterface;
+
+/**
+ * Reference implementation: describes a 'color' ProductOption's values as
+ * carrying a hex code in `meta.hex`, editable via a Filament color picker.
+ * Not auto-registered — a shop opts in via config('core.product_option_types').
+ */
+class ColorOptionType implements ProductOptionTypeInterface
+{
+    public static function getKey(): string
+    {
+        return 'color';
+    }
+
+    public function getMetaForm(): array
+    {
+        return [
+            ColorPicker::make('meta.hex')
+                ->label('Color')
+                ->required(),
+        ];
+    }
+}

src/Product/Services/ProductIndexer.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Modules\Core\Search;
+namespace Modules\Core\Product\Services;
 
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
@@ -13,9 +13,9 @@ use Modules\Core\Review\Models\ProductReview;
 use Spatie\MediaLibrary\MediaCollections\Models\Media;
 
 /**
- * Extends Lunar's own indexer so Modules\Core\Catalog\ProductService can serve both
+ * Extends Lunar's own indexer so Modules\Core\Product\Services\ProductService can
- * listing/filtering AND single-product lookups from Meilisearch alone — one data
+ * serve both listing/filtering AND single-product lookups from Meilisearch alone —
- * source, no separate database read path for a product detail page. Adds:
+ * one data source, no separate database read path for a product detail page. Adds:
  *   - collections (ids, filterable) and collection_names (display)
  *   - slugs (every locale's Url::slug for the product, filterable) — lets
  *     ProductService::getBySlug() resolve a product from the index directly, with
@@ -56,6 +56,14 @@ class ProductIndexer extends BaseProductIndexer
         ];
     }
 
+    public function getSortableFields(): array
+    {
+        return [
+            ...parent::getSortableFields(),
+            'price',
+        ];
+    }
+
     public function makeAllSearchableUsing(Builder $query): Builder
     {
         return parent::makeAllSearchableUsing($query)->with([
@@ -89,7 +97,7 @@ class ProductIndexer extends BaseProductIndexer
         $data['average_rating'] = $reviews->isEmpty() ? null : round($reviews->avg('rating'), 1);
         $data['channel_ids'] = $model->channels()
             ->wherePivot('enabled', true)
-            ->pluck('id')
+            ->pluck('lunar_channels.id')
             ->toArray();
 
         return $data;

src/Product/Services/ProductOptionTypeManager.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Modules\Core\Product\Services;
+
+use Illuminate\Support\Collection;
+use Modules\Core\Product\Contracts\ProductOptionTypeInterface;
+
+/**
+ * Resolves an admin-selected option type key to the `ProductOptionTypeInterface`
+ * describing it. The selection (which key a given `Lunar\Models\ProductOption` uses)
+ * is stored per-option in `ProductOption::meta['option_type']` — deliberately not
+ * tied to the option's `handle`, since a shop's own handle naming (e.g. transliterated
+ * Greek, legacy imports) shouldn't have to match a type's key.
+ *
+ * The available keys come from `config('core.product_option_types')` — a plain list,
+ * not a config array, because the mapping from option to type is an admin's per-option
+ * choice made in the UI (see ValuesRelationManagerExtension/ProductOptionResourceExtension),
+ * not something config alone can express.
+ */
+class ProductOptionTypeManager
+{
+    /**
+     * @return Collection<string, ProductOptionTypeInterface> keyed by getKey()
+     */
+    public function all(): Collection
+    {
+        return collect(config('core.product_option_types', []))
+            ->map(fn (string $class) => app($class))
+            ->keyBy(fn (ProductOptionTypeInterface $type) => $type::getKey());
+    }
+
+    public function resolve(?string $key): ?ProductOptionTypeInterface
+    {
+        if ($key === null) {
+            return null;
+        }
+
+        return $this->all()->get($key);
+    }
+}

src/Product/Services/ProductSearchService.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Modules\Core\Search;
+namespace Modules\Core\Product\Services;
 
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Support\Facades\App;

src/Product/Services/ProductService.php

@@ -0,0 +1,168 @@
+<?php
+
+namespace Modules\Core\Product\Services;
+
+use Illuminate\Contracts\Pagination\LengthAwarePaginator as LengthAwarePaginatorContract;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\App;
+use Lunar\Base\AttributeManifest;
+use Lunar\FieldTypes\TranslatedText;
+use Lunar\Models\Product;
+use Modules\Core\Localization\Services\LanguageCache;
+use Modules\Core\Product\DTOs\ProductFilters;
+use Modules\Core\Product\Enums\ProductSort;
+
+/**
+ * Storefront product listing/filtering AND single-product lookup, all reading directly
+ * from the Meilisearch index (Modules\Core\Product\Services\ProductIndexer) - one data
+ * source, no ->get() model hydration anywhere in this service. Callers get plain arrays
+ * of the indexed document, not Eloquent models.
+ *
+ * Full-text query search lives separately in Modules\Core\Product\Services\
+ * ProductSearchService; this service is for browsing/filtering without a search term.
+ */
+class ProductService
+{
+    public function __construct(
+        private readonly LanguageCache $languages,
+        private readonly AttributeManifest $attributes,
+    ) {}
+
+    /**
+     * Returns a real LengthAwarePaginator (not Scout's own paginateRaw() result -
+     * see "Meilisearch driver quirk" below) so a controller/view gets normal
+     * pagination behaviour ($products->links(), JSON serialization, etc.)
+     * without ever touching the raw Meilisearch response directly.
+     */
+    public function list(?ProductFilters $filters = null, int $perPage = 24, int $page = 1, ?ProductSort $sort = null): LengthAwarePaginator
+    {
+        $options = ['filter' => $this->buildFilter($filters)];
+
+        if ($sort !== null) {
+            $options['sort'] = [$sort->toMeilisearchSort()];
+        }
+
+        $paginator = Product::search('')
+            ->options($options)
+            ->paginateRaw(perPage: $perPage, page: $page);
+
+        $data = collect($this->hitsFrom($paginator))
+            ->map(fn (array $product) => $this->withLocalizedFields($product))
+            ->all();
+
+        return new LengthAwarePaginator(
+            items: $data,
+            total: $paginator->total(),
+            perPage: $paginator->perPage(),
+            currentPage: $paginator->currentPage(),
+            options: ['path' => LengthAwarePaginator::resolveCurrentPath()],
+        );
+    }
+
+    /**
+     * Look up a single product by its URL slug (any locale - slugs are indexed across
+     * all languages, see Modules\Core\Product\Services\ProductIndexer). Returns the full
+     * indexed product document, or null if no product has that slug.
+     */
+    public function getBySlug(string $slug): ?array
+    {
+        return $this->findOneWhere('slugs = "'.addcslashes($slug, '"\\').'"');
+    }
+
+    /**
+     * Look up a single product by its primary key. Returns the full indexed product
+     * document, or null if no product has that id.
+     */
+    public function getById(int $id): ?array
+    {
+        return $this->findOneWhere("id = \"{$id}\"");
+    }
+
+    private function findOneWhere(string $filter): ?array
+    {
+        $paginator = Product::search('')
+            ->options(['filter' => $filter])
+            ->paginateRaw(perPage: 1, page: 1);
+
+        $product = $this->hitsFrom($paginator)[0] ?? null;
+
+        return $product !== null ? $this->withLocalizedFields($product) : null;
+    }
+
+    /**
+     * Resolves every translated Product attribute's current-locale value from the
+     * indexer's per-locale `{handle}_{locale}` fields (e.g. `name_el`, `name_en`,
+     * `seo_title_el`, ...) into a plain `{handle}` key, falling back to the store's
+     * default language (LanguageCache::defaultLocale()) when the current locale
+     * has no translation - e.g. a product with no English copy yet still shows its
+     * Greek name on /en/ rather than rendering blank.
+     *
+     * Which handles are translated is read from AttributeManifest - the same
+     * source Lunar's own ScoutIndexer reads when exploding a TranslatedText
+     * attribute into `{handle}_{locale}` keys at index time - rather than a fixed
+     * list, so a store's own custom translated attributes (e.g. `seo_title`) are
+     * picked up automatically with no change here. The raw per-locale keys are
+     * then stripped, since once resolved, callers only ever need the one that
+     * matched the current locale.
+     *
+     * Deliberately not config('app.locale') - App::setLocale() overwrites that
+     * config value on every request, so by request time it's just whatever the
+     * current locale already is, not a stable fallback.
+     */
+    private function withLocalizedFields(array $product): array
+    {
+        $locale = App::getLocale();
+        $fallbackLocale = $this->languages->defaultLocale();
+        $availableLocales = $this->languages->availableLocales();
+
+        foreach ($this->translatedAttributeHandles() as $handle) {
+            $product[$handle] = $product[$handle.'_'.$locale] ?? $product[$handle.'_'.$fallbackLocale] ?? null;
+
+            foreach ($availableLocales as $availableLocale) {
+                unset($product[$handle.'_'.$availableLocale]);
+            }
+        }
+
+        return $product;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function translatedAttributeHandles(): array
+    {
+        return $this->attributes->getSearchableAttributes((new Product)->getMorphClass())
+            ->filter(fn ($attribute) => $attribute->type === TranslatedText::class)
+            ->pluck('handle')
+            ->all();
+    }
+
+    /**
+     * For the Meilisearch driver, Scout's paginateRaw() puts the whole raw response
+     * (hits, query, processingTimeMs, ...) in items(), not a plain list of hits - the
+     * actual documents are under the 'hits' key.
+     */
+    private function hitsFrom(LengthAwarePaginatorContract $paginator): array
+    {
+        $rawResponse = $paginator->items();
+
+        return collect($rawResponse['hits'] ?? [])->values()->all();
+    }
+
+    private function buildFilter(?ProductFilters $filters): ?string
+    {
+        if ($filters === null) {
+            return null;
+        }
+
+        $clauses = Collection::make([
+            $filters->collectionId !== null ? "collections = \"{$filters->collectionId}\"" : null,
+            $filters->brand !== null ? 'brand = "'.addcslashes($filters->brand, '"\\').'"' : null,
+            $filters->minPrice !== null ? "price >= {$filters->minPrice}" : null,
+            $filters->maxPrice !== null ? "price <= {$filters->maxPrice}" : null,
+        ])->filter();
+
+        return $clauses->isEmpty() ? null : $clauses->join(' AND ');
+    }
+}

src/Providers/LocalizationServiceProvider.php

@@ -11,15 +11,26 @@ use Modules\Core\Localization\Events\LanguageUpdated;
 use Modules\Core\Localization\Events\TranslationCreated;
 use Modules\Core\Localization\Events\TranslationDeleted;
 use Modules\Core\Localization\Events\TranslationUpdated;
-use Modules\Core\Localization\LanguageCacheObserver;
 use Modules\Core\Localization\Listeners\FlushLanguageCache;
 use Modules\Core\Localization\Listeners\FlushTranslationCache;
 use Modules\Core\Localization\Listeners\LogTranslationActivity;
 use Modules\Core\Localization\Listeners\MigrateTranslationsForRenamedLanguage;
-use Modules\Core\Localization\LocaleMiddleware;
+use Modules\Core\Localization\Middleware\LocaleMiddleware;
+use Modules\Core\Localization\Models\LanguageLine;
+use Modules\Core\Localization\Observers\LanguageCacheObserver;
 
 class LocalizationServiceProvider extends ServiceProvider
 {
+    public function register(): void
+    {
+        // Must run before Spatie\TranslationLoader\TranslationServiceProvider's
+        // register() merges its own config defaults - mergeConfigFrom() only fills
+        // in keys not already set, so setting this here (regardless of provider
+        // boot order) makes it win over the package's default
+        // Spatie\TranslationLoader\LanguageLine::class.
+        config(['translation-loader.model' => LanguageLine::class]);
+    }
+
     public function boot(): void
     {
         $this->app['router']->aliasMiddleware('locale', LocaleMiddleware::class);

src/Providers/ProductServiceProvider.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use Lunar\Models\ProductOption;
+use Lunar\Models\ProductOptionValue;
+use Modules\Core\Product\Observers\ProductOptionReindexObserver;
+
+class ProductServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        $observer = new ProductOptionReindexObserver;
+
+        ProductOption::saved(fn (ProductOption $option) => $observer->optionSaved($option));
+        ProductOption::deleted(fn (ProductOption $option) => $observer->optionDeleted($option));
+
+        ProductOptionValue::saved(fn (ProductOptionValue $value) => $observer->valueSaved($value));
+        ProductOptionValue::deleted(fn (ProductOptionValue $value) => $observer->valueDeleted($value));
+    }
+}

src/Providers/ReviewServiceProvider.php

@@ -9,8 +9,8 @@ use Modules\Core\Review\Models\ProductReview;
  * Keeps a product's Meilisearch document in sync with its reviews. A review is
  * created/edited independently of its product (customer submission, staff reply),
  * so the product's own save/update events never fire for it — without this listener,
- * Modules\Core\Search\ProductIndexer's review data would only refresh on the next
+ * Modules\Core\Product\Services\ProductIndexer's review data would only refresh on
- * full product reindex.
+ * the next full product reindex.
  */
 class ReviewServiceProvider extends ServiceProvider
 {

src/Review/Models/ProductReview.php

@@ -5,8 +5,11 @@ namespace Modules\Core\Review\Models;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Lunar\Models\Product;
+use Spatie\Image\Enums\BorderType;
+use Spatie\Image\Enums\Fit;
 use Spatie\MediaLibrary\HasMedia;
 use Spatie\MediaLibrary\InteractsWithMedia;
+use Spatie\MediaLibrary\MediaCollections\Models\Media;
 
 class ProductReview extends Model implements HasMedia
 {
@@ -30,4 +33,23 @@ class ProductReview extends Model implements HasMedia
     {
         $this->addMediaCollection(self::IMAGES_COLLECTION);
     }
+
+    /**
+     * Unlike Product/ProductVariant, this model sits outside Lunar's own
+     * MediaDefinitionsInterface (Lunar\Base\StandardMediaDefinitions), which is
+     * what registers the 'small' conversion those models get automatically. Without
+     * this, Modules\Core\Product\Services\ProductIndexer::mapMedia() — shared across
+     * product, variant, and review media — throws Spatie\MediaLibrary\MediaCollections\
+     * Exceptions\InvalidConversion the first time a review has an image, since
+     * $media->getUrl('small') has no matching conversion to resolve.
+     */
+    public function registerMediaConversions(?Media $media = null): void
+    {
+        $this->addMediaConversion('small')
+            ->fit(Fit::Fill, 300, 300)
+            ->border(0, BorderType::Overlay, color: '#FFF')
+            ->background('#FFF')
+            ->sharpen(10)
+            ->keepOriginalImageFormat();
+    }
 }