@live-change/frontend-template 0.9.203 → 0.9.204

package/.claude/rules/live-change-backend-actions-views-triggers.md

@@ -1,6 +1,6 @@
 ---
 description: Rules for implementing actions, views, and triggers in LiveChange services
-globs: **/services/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 ---
 
 # LiveChange backend – actions, views, triggers (Claude Code)
@@ -52,6 +52,48 @@ definition.action({
 - Views should be simple query endpoints over models.
 - Prefer `indexObjectGet` / `indexRangeGet` instead of scanning whole tables.
 
+### Range view guardrails (for RangeViewer/rangeBuckets consumers)
+
+- For index-backed paginated lists, prefer `Model.sortedIndexRangePath(indexName, keyPrefix, App.extractRange(props))`.
+- Do not use `indexRangePath` semantics for views consumed by bucket-based range UI.
+- Keep `gt/gte/lt/lte` as cursor pagination fields, not domain filter fields.
+- If you need filtering by month/year/status, design index prefix for it first.
+- Use `App.utils.prefixRange` as backend fallback only when index redesign is not feasible.
+
+### Standalone index guardrail
+
+- If an index combines peer data streams (union of multiple tables), define it as service-level `definition.index(...)` (prefer separate `indexes.js`), not as `model.indexes` inside one arbitrary model.
+- Use model `indexes` only when one model is the clear owner of index semantics.
+
+### Index function serialization constraint
+
+Index functions (`definition.index({ function })` and model-level `indexes: { name: { function } }`) are **serialized via `toString()`** and executed on a remote server. They **cannot reference anything outside their own function body** — no outer variables, no imported functions, no module-scope helpers.
+
+```js
+// ❌ BROKEN — helper is outside the function, undefined at runtime
+function mapRow(obj) { return { id: obj.name + '_' + obj.id, to: obj.id } }
+
+definition.index({
+  name: 'myIndex',
+  function: async (input, output, { tableName }) => {
+    const table = await input.table(tableName)
+    await table.map(mapRow).to(output)       // mapRow is undefined!
+  },
+  parameters: { tableName: definition.name + '_MyModel' }
+})
+
+// ✅ CORRECT — helper is inside the function body
+definition.index({
+  name: 'myIndex',
+  function: async (input, output, { tableName }) => {
+    const mapRow = obj => ({ id: obj.name + '_' + obj.id, to: obj.id })
+    const table = await input.table(tableName)
+    await table.map(mapRow).to(output)
+  },
+  parameters: { tableName: definition.name + '_MyModel' }
+})
+```
+
 Example of a range view:
 
 ```js
@@ -159,6 +201,12 @@ definition.trigger({
 
 Check `data`/`oldData`: both present = update, only `data` = create, only `oldData` = delete.
 
+## Cron-service — schedules, intervals, and admin UI
+
+- For **cron-like** or **repeating-interval** execution of a **trigger**, use **`@live-change/cron-service`** (**Schedule** / **Interval**) plus **task-service** triggers — do not sketch “only a timer” without considering cron models and **`changeCron_Schedule`** / **`changeCron_Interval`** timer lifecycle.
+- Reference admin flow (see **task-frontend**): **`setSchedule`** / **`setInterval`** via **`ActionForm`**, lists via **`path.cron.schedules`** / **`path.cron.intervals`**, enrich rows with **`.with()`** for **`scheduleInfo`** / **`intervalInfo`**, **`runState`** (`jobType` **`cron_Schedule`** or **`cron_Interval`**), and **`task.tasksByCauseAndCreatedAt`**; delete with **`deleteSchedule`** / **`deleteInterval`**.
+- **Schedule** time fields (**minute**, **hour**, **day**, **dayOfWeek**, **month**): use **`NaN`** for “every” at that granularity; see **`15-cron-and-intervals.md`** (section **API used by task-frontend**).
+
 ## Granting access on object creation
 
 When a model uses `entity` with `writeAccessControl` / `readAccessControl`, the auto-generated CRUD checks roles but does **not** grant them automatically. The creator must be explicitly granted roles — typically `'owner'` — otherwise they cannot access their own object.

package/.claude/rules/live-change-backend-models-and-relations.md

@@ -32,6 +32,25 @@ properties: {
 }
 ```
 
+## Relation arity (critical)
+
+Always separate:
+
+- **annotation arity** — can the annotation be a list of configs
+- **parent tuple arity** — can one config include multiple parents/dimensions
+
+| Relation | Annotation arity | Parent tuple arity |
+|---|---|---|
+| `propertyOf`, `itemOf`, `boundTo` | single config only | `what` can be one model or `[A, B, ...]` |
+| `relatedTo` | single config or config list | each config uses `what` with one model or `[A, B, ...]` |
+| `propertyOfAny`, `itemOfAny`, `boundToAny` | single config only | `to` can contain one or many names |
+| `relatedToAny` | single config or config list | each config uses `to` with one or many names |
+
+Guardrail:
+
+- valid: `propertyOf: { what: [A, B] }`
+- invalid: `propertyOf: [configA, configB]`
+
 ## `userItem` – belongs to the signed-in user
 
 Use when the model is owned by the currently signed-in user.
@@ -113,7 +132,7 @@ Effects:
 ## `propertyOf` with multiple parents (1:1 link to each)
 
 Sometimes a model is a dedicated 1:1 link between entities (for example: invoice ↔ contractor in a specific role).
-Most commonly this is 1–2 parents, but `propertyOf` can point to **any number** of parent models (including 3+), if that matches the domain semantics.
+Most commonly this is 1–2 parents, but `what` can point to **any number** of parent models (including 3+), if that matches the domain semantics.
 
 In that case:
 
@@ -132,10 +151,9 @@ definition.model({
   properties: {
     // optional extra fields
   },
-  propertyOf: [
-    { what: CostInvoice },
-    { what: Contractor }
-  ]
+  propertyOf: {
+    what: [CostInvoice, Contractor]
+  }
 })
 ```
 
@@ -180,7 +198,7 @@ Relations automatically add **identifier fields** and **indexes** to the model.
 | `propertyOfAny: { to: ['owner'] }` | `ownerType`, `owner` | `byOwner` (hash) |
 | `boundTo: { what: Device }` | `device` | `byDevice` (hash) |
 
-For multi-parent relations (e.g. `propertyOf: [{ what: A }, { what: B }]`), all index combinations are created (`byA`, `byB`, `byAAndB`).
+For multi-parent relations (e.g. `propertyOf: { what: [A, B] }`), all index combinations are created (`byA`, `byB`, `byAAndB`).
 
 ```js
 // ✅ Correct — only define YOUR fields

package/.claude/rules/live-change-service-structure.md

@@ -1,13 +1,13 @@
 ---
 description: Rules for LiveChange service directory structure and file organization
-globs: **/services/**/*.js
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
 ---
 
 # LiveChange Service Structure
 
 Every LiveChange service **must** be a directory, not a single file.
 
-## Required structure
+## Required structureW
 
 ```
 server/services/<serviceName>/

package/.claude/settings.json

@@ -22,7 +22,9 @@
       "Bash(cp /home/m8/IdeaProjects/live-change/.claude/rules/live-change-backend-event-sourcing.md /home/m8/IdeaProjects/live-change/automation/.claude/rules/live-change-backend-event-sourcing.md)",
       "Bash(find /home/m8/IdeaProjects/live-change/live-change-stack/framework -type f \\\\\\(-name *.ts -o -name *.js \\\\\\))",
       "Bash(find /home/m8/IdeaProjects/live-change/live-change-stack/services -type f -name *.js)",
-      "Bash(grep -r \"userItem\\\\|userProperty\" /home/m8/IdeaProjects/live-change/live-change-stack/services/user-service --include=*.js)"
+      "Bash(grep -r \"userItem\\\\|userProperty\" /home/m8/IdeaProjects/live-change/live-change-stack/services/user-service --include=*.js)",
+      "Bash(find /home/m8/IdeaProjects/live-change/auto-firma/app -maxdepth 2 -type f \\\\\\(-name jest.config.* -o -name vitest.config.* -o -name *.test.js -o -name *.test.ts \\\\\\))",
+      "Bash(find /home/m8/IdeaProjects/live-change/auto-firma/app -maxdepth 3 -type d -not -path */node_modules* -not -path */dist* -not -path */backups* -not -path */dev_docker_home* -not -path */storage* -not -path */tmp.db*)"
     ],
     "additionalDirectories": [
       "/home/m8/IdeaProjects/live-change/.claude/skills/create-skills-and-rules",

package/.claude/skills/live-change-backend-change-triggers/SKILL.md

@@ -112,6 +112,21 @@ definition.trigger({
 
 This means: when a user creates a Schedule via the UI or API, the timer is automatically set up. When they update it, the old timer is canceled and a new one created. When they delete it, the timer is canceled.
 
+## Cron-service — planning and admin UI guardrails
+
+When the domain needs **wall-clock schedules** or **fixed repeating intervals** that run a **trigger**, default to **`@live-change/cron-service`** (models **Schedule** / **Interval**, internal **timer** + **changeCron_*** lifecycle), not ad-hoc timers only.
+
+**Backend:** define the **target `definition.trigger`** in your service; put **Schedule** / **Interval** rows in **cron** with **`trigger: { name, service, properties, returnTask }`**. Rely on **`changeCron_Schedule`** / **`changeCron_Interval`** for timer repair (already implemented in cron-service).
+
+**Admin / task-frontend-style UI:** use the same integration as the reference pages:
+
+- **Create:** `ActionForm` with `service="cron"` and `action="setSchedule"` or `action="setInterval"` (relations-driven forms).
+- **List:** `RangeViewer` + `path.cron.schedules` / `path.cron.intervals` with **`reverseRange(range)`** as needed.
+- **Per row:** `.with()` → `scheduleInfo` / `intervalInfo`, `runState` (`jobType` **`cron_Schedule`** or **`cron_Interval`**, **`job`** = id), and `task.tasksByCauseAndCreatedAt` for recent runs.
+- **Delete:** `api.actions.cron.deleteSchedule` / `deleteInterval`.
+
+See **server doc** `15-cron-and-intervals.md` → section **“API used by task-frontend”** for path examples and **Schedule** field semantics (**`NaN`** = “every” for that field).
+
 ## Step 4 – Specific lifecycle triggers (alternative)
 
 If you only care about one lifecycle event, use the specific variant:

package/.claude/skills/live-change-dao-protocol/SKILL.md

@@ -0,0 +1,46 @@
+---
+description: Jak poprawnie wywoływać akcje i widoki frameworka LiveChange przez surowy protokół DAO.
+---
+
+# LiveChange DAO Protocol Arguments
+
+Kiedy komunikujesz się z frameworkiem LiveChange używając surowego protokołu `@live-change/dao` (np. z C++, Pythona, Rusta, Go lub dowolnego innego klienta nie-JS), MUSISZ ZAWSZE przekazywać argumenty jako **tablicę**.
+
+Framework traktuje argumenty żądań (request) i obserwabli (observable) DAO jak argumenty funkcji i używa operatora spread (`...args`), aby przekazać je do bazowych funkcji akcji lub widoków. Jeśli przekażesz obiekt zamiast tablicy, serwer rzuci błąd `TypeError: Spread syntax requires ...iterable[Symbol.iterator] to be a function`.
+
+Nawet jeśli akcja lub widok oczekuje pojedynczego obiektu jako parametru, ten obiekt MUSI być opakowany w jednoelementową tablicę.
+
+## Przykład w C++ (używając nlohmann/json)
+
+### Niepoprawnie ❌
+```cpp
+nlohmann::json args = {
+  {"pairingKey", "123"},
+  {"connectionType", "device"}
+};
+connection->request({"serviceName", "actionName"}, args, settings);
+```
+
+### Poprawnie ✅
+```cpp
+// Wrap the object in an array
+auto args = {
+  nlohmann::json::object({
+    {"pairingKey", "123"},
+    {"connectionType", "device"}
+  })
+};
+connection->request({"serviceName", "actionName"}, args, settings);
+```
+
+Lub jawnie:
+```cpp
+nlohmann::json args = nlohmann::json::array({
+  nlohmann::json::object({
+    {"pairingKey", "123"},
+    {"connectionType", "device"}
+  })
+});
+```
+
+Zawsze upewnij się, że Twój payload `args` jest tablicą przed wysłaniem go przez połączenie DAO.

package/.claude/skills/live-change-design-actions-views-triggers/SKILL.md

@@ -79,6 +79,116 @@ definition.action({
    - use model paths (`Model.path`, `Model.rangePath`, `Model.sortedIndexRangePath`, `Model.indexObjectPath`)
    - use `...App.rangeProperties` + `App.extractRange(props)` for range views
 
+### Step 2a – Prefix-aware range filtering
+
+When you query an index with `Model.sortedIndexRangePath(indexName, keyPrefix, range)`, remember:
+
+- `keyPrefix` is matched first (for example `[bankAccount]` or `[bankAccount, month]`).
+- `range.gt/gte/lt/lte` is applied to full serialized index keys, not to a single field.
+- If you need optional narrowing, pass a dedicated filter parameter (`month`, `state`, etc.) and keep range for cursor pagination.
+
+```js
+definition.view({
+  name: 'bankTransactionsByBankAccountAndDate',
+  properties: {
+    bankAccount: { type: String },
+    month: { type: String },
+    ...App.rangeProperties
+  },
+  returns: { type: Array, of: { type: Object } },
+  async daoPath({ bankAccount, month, ...props }) {
+    const range = App.extractRange(props)
+    if(month) {
+      const prefix = [bankAccount, month].map(v => JSON.stringify(v)).join(':')
+      return BankTransaction.rangePath(App.utils.prefixRange(range, prefix, prefix + ':'))
+    }
+    return BankTransaction.sortedIndexRangePath('byBankAccountAndDate', [bankAccount], range)
+  }
+})
+```
+
+If filtering by month is a frequent query, prefer a dedicated index like `byBankAccountAndMonthAndDate` and query it with:
+
+```js
+BankTransaction.sortedIndexRangePath('byBankAccountAndMonthAndDate', [bankAccount, month], range)
+```
+
+For that index, prefer this function-index style:
+
+```js
+function: async (input, output, { tableName }) => {
+  const table = await input.table(tableName)
+  const mapper = obj => ({
+    id: [obj.bankAccount, obj.date?.slice(0, 7), obj.date]
+      .map(v => JSON.stringify(v)).join(':') + '_' + obj.id,
+    to: obj.id
+  })
+  await table.map(mapper).to(output)
+}
+```
+
+`map()` automatically filters out `null`, so you can keep mapper logic concise.
+
+### Step 2b – RangeViewer/rangeBuckets compatibility
+
+When a view is consumed by `RangeViewer` or `rangeBuckets`:
+
+- prefer `Model.sortedIndexRangePath(...)` for index-backed list views,
+- keep `App.extractRange(props)` as pagination cursor input,
+- do not reinterpret `gt/gte/lt/lte` as domain filters.
+
+Anti-patterns:
+
+- using `indexRangePath` for frontend bucket pagination flow,
+- injecting custom month/year bounds into cursor fields in frontend,
+- rewriting cursor values in backend with unrelated filter semantics.
+
+Preferred filtering strategy:
+
+1. design index prefix for frequent filters,
+2. use `App.utils.prefixRange` only as backend fallback,
+3. keep string min/max hacks as last resort.
+
+### Step 2c – Standalone indexes for union/equal sources
+
+When index rows are built from multiple equal tables (union-like flow), do not force the index into one model definition.
+
+Use `definition.index(...)` at service level (typically `indexes.js`) when:
+
+- index combines rows from two or more source tables,
+- source tables are peer entities (no natural single owner model),
+- index is a projection layer for cross-table reads.
+
+> **IMPORTANT — serialization constraint:** Index functions are serialized via `toString()` and executed remotely. All helpers, mappers, and variables **must be defined inside the function body**. References to outer scope (module-level functions, imports) will be `undefined` at runtime.
+
+Example:
+
+```js
+definition.index({
+  name: 'Urls',
+  function: async (input, output) => {
+    const mapRedirect = obj => obj && ({
+      id: /* composed key */, to: obj.target
+    })
+    const mapCanonical = obj => obj && ({
+      id: /* composed key */, to: obj.target
+    })
+
+    await input.table('url_Redirect').onChange((obj, oldObj) =>
+      output.change(mapRedirect(obj), mapRedirect(oldObj))
+    )
+    await input.table('url_Canonical').onChange((obj, oldObj) =>
+      output.change(mapCanonical(obj), mapCanonical(oldObj))
+    )
+  }
+})
+```
+
+Decision rule:
+
+- model-local index -> `definition.model({ indexes: ... })`,
+- union/peer-source index -> standalone `definition.index(...)` in `indexes.js`.
+
 ### Example: `daoPath` (preferred, DAO-backed)
 
 ```js

package/.claude/skills/live-change-design-models-relations/SKILL.md

@@ -62,6 +62,25 @@ properties: {
 }
 ```
 
+## Step 2b – Relation arity rules (critical)
+
+Treat arity on two levels:
+
+- **Annotation arity**: can the annotation itself be a list of configs?
+- **Parent tuple arity**: can one config point to multiple parents/dimensions?
+
+| Relation | Annotation arity | Parent tuple arity |
+|---|---|---|
+| `propertyOf`, `itemOf`, `boundTo` | single config only | `what` can be one model or `[A, B, ...]` |
+| `relatedTo` | single config or config list | each config uses `what` with one model or `[A, B, ...]` |
+| `propertyOfAny`, `itemOfAny`, `boundToAny` | single config only | `to` can contain one or many names |
+| `relatedToAny` | single config or config list | each config uses `to` with one or many names |
+
+Guardrail:
+
+- valid: `propertyOf: { what: [A, B] }`
+- invalid: `propertyOf: [configA, configB]`
+
 ## Step 3 – Configure the relation
 
 ### `userItem`
@@ -110,7 +129,7 @@ so the relations/CRUD generator can treat it as a relation rather than a plain `
 
 Notes:
 
-- Usually you’ll have 1–2 parents, but the `propertyOf` list may contain **any number** of parent models (including 3+).
+- Usually you’ll have 1–2 parents, but `what` may contain **any number** of parent models (including 3+).
 - If the entity is a relation, avoid adding manual `...Id` fields in `properties` just to represent the link — CRUD generators won’t treat it as a relation.
 
 Example:
@@ -124,10 +143,9 @@ definition.model({
   properties: {
     // optional extra fields
   },
-  propertyOf: [
-    { what: CostInvoice },
-    { what: Contractor }
-  ]
+  propertyOf: {
+    what: [CostInvoice, Contractor]
+  }
 })
 ```
 
@@ -168,6 +186,46 @@ indexes: {
 
 3. Use these indexes in views/actions, via `indexObjectGet` / `indexRangeGet`.
 
+### Step 5b – Use `function` indexes for derived keys
+
+Use a `function` index when key parts are not stored directly as properties (for example `yearMonth` derived from `date`).
+
+Key rules:
+
+- Keep index entries stable and deterministic.
+- Build composite keys as serialized parts joined with `:` and append `_' + id`.
+- Emit `{ id, to }` objects so `to` points to the source model id.
+- Prefer `table.map(mapper).to(output)` over manual `onChange(...output.change...)`.
+- `map()` drops `null` results automatically, so mapper can stay clean.
+
+Example:
+
+```js
+indexes: {
+  byBankAccountAndMonthAndDate: {
+    function: async (input, output, { tableName }) => {
+      const table = await input.table(tableName)
+      const mapper = obj => ({
+        id: [
+          obj.bankAccount,
+          obj.date?.slice(0, 7),   // YYYY-MM month bucket
+          obj.date
+        ].map(v => JSON.stringify(v)).join(':') + '_' + obj.id,
+        to: obj.id
+      })
+      await table.map(mapper).to(output)
+    },
+    parameters: {
+      tableName: definition.name + '_BankTransaction'
+    }
+  }
+}
+```
+
+This format matches how property indexes are serialized internally and works well with range-prefix filtering in views.
+
+> **IMPORTANT — serialization constraint:** Function indexes are serialized via `toString()` and executed remotely. The mapper and all helpers **must be defined inside the function body** — not in module scope. References to outer variables or imports will be `undefined` at runtime.
+
 ## Step 6 – Set access control on relations
 
 1. For `userItem`, `itemOf`, and `propertyOf`, always define:

package/.claude/skills/live-change-frontend-data-views/SKILL.md

@@ -38,6 +38,21 @@ const [article, comments] = await Promise.all([
 ])
 ```
 
+- Call `usePath()` **once** at the top of `setup` (synchronously). Inside `computed`, use only the returned `path` object to build paths — **never** call `usePath()` or the legacy `path()` inside the getter (there is often no active component instance, which breaks `getCurrentInstance()` / `appContext`).
+
+Wrong:
+
+```javascript
+computed(() => usePath().blog.article({ article: id }))
+```
+
+Right:
+
+```javascript
+const path = usePath()
+const articlePath = computed(() => path.blog.article({ article: id }))
+```
+
 In templates access `.value`:
 
 ```vue
@@ -47,7 +62,26 @@ In templates access `.value`:
 </div>
 ```
 
-## Step 2 – Load related objects with `.with()`
+## Step 2 – One-time fetches with `useFetch`
+
+When you need data once (e.g. after an upload, in an event handler), use `useFetch` instead of `live`:
+
+```javascript
+import { usePath, useFetch } from '@live-change/vue3-ssr'
+
+const path = usePath()
+const data = await useFetch(path.paperInvoice.invoiceFileInfo({ invoiceFile: fileId }))
+```
+
+**Do NOT use `api.get()` with Path objects.** `path.service.view()` returns a Path object (with `.what`, `.more`, `.to` properties), not a raw array. `api.get()` only accepts raw arrays like `['service', 'view', { params }]`.
+
+| Method | Input | Returns | Use when |
+|---|---|---|---|
+| `live(path)` | Path or array | Reactive Ref | Live-updating data |
+| `useFetch(path)` | Path or array | Promise | One-time fetch |
+| `api.get([...])` | Raw array only | Promise | Low-level, avoid in app code |
+
+## Step 3 – Load related objects with `.with()`
 
 Chain `.with()` to attach related data to each item:
 
@@ -64,6 +98,40 @@ const articlesPath = computed(() =>
 const [articles] = await Promise.all([live(articlesPath)])
 ```
 
+### `.with()` callback guardrails
+
+Treat `.with(item => ...)` as a declarative Path DSL builder:
+
+- the callback receives a proxy, not a hydrated runtime record
+- do not place side effects or command calls inside `.with(...)`
+- do not use imperative branching like `if(item.type === '...')` in the callback
+
+Use `$switch` for conditional path branching:
+
+```javascript
+const settlementsPath = computed(() =>
+  path.accounting.settlementsByTransaction({
+    transactionType: 'bankAccount_BankTransaction',
+    transaction: transactionId,
+    range: { limit: 256 }
+  }).with(settlement => settlement.subjectType.$switch({
+    invoice_CostInvoice: path.invoice.costInvoice({ costInvoice: settlement.subject }),
+    invoice_IncomeInvoice: path.invoice.incomeInvoice({ incomeInvoice: settlement.subject }),
+    hr_CivilContract: path.hr.civilContract({ civilContract: settlement.subject })
+  }).$bind('subjectDoc'))
+)
+```
+
+Production-style pattern reference:
+
+```javascript
+p.url.urlsByTargetAndPath({ targetType, domain, path: urlPath })
+  .with(url => url.type.$switch({
+    canonical: null,
+    redirect: p.url.canonical({ targetType, target: url.target })
+  }).$bind('canonical'))
+```
+
 Access in template:
 
 ```vue
@@ -88,7 +156,7 @@ const eventPath = computed(() =>
 )
 ```
 
-## Step 3 – Conditional loading with `useClient`
+## Step 4 – Conditional loading with `useClient`
 
 Use `useClient()` to check authentication state and conditionally build paths:
 
@@ -134,7 +202,7 @@ When the path is `null` / `false` / `undefined`, `live()` returns a ref with `nu
 </template>
 ```
 
-## Step 4 – Dependent paths
+## Step 5 – Dependent paths
 
 When one path depends on data from another, load them sequentially:
 
@@ -154,7 +222,7 @@ const [author] = await Promise.all([live(authorPath)])
 
 Or use `.with()` to combine them in a single query (preferred when possible).
 
-## Step 5 – Props-based paths in components
+## Step 6 – Props-based paths in components
 
 When building reusable components that receive IDs as props:
 
@@ -179,6 +247,7 @@ When building reusable components that receive IDs as props:
 | Pattern | When to use |
 |---|---|
 | `computed(() => path.xxx(...))` | Path depends on reactive values |
+| `useFetch(path.xxx(...))` | One-time data fetch (not reactive) |
 | `.with(item => path.yyy(...).bind('field'))` | Attach related objects |
 | `client.value.user && path.xxx(...)` | Load only when authenticated |
 | `client.value.roles.includes('admin')` | Load/show only for specific roles |

package/.claude/skills/live-change-frontend-range-list/SKILL.md

@@ -27,6 +27,19 @@ function articlesPathRange(range) {
 }
 ```
 
+## Step 1a – Hard rules for index-backed ranges
+
+For lists loaded with `RangeViewer` / `rangeBuckets`:
+
+- backend views should use `sortedIndexRangePath`, not `indexRangePath`,
+- keep `range.gt/gte/lt/lte` for pagination cursor only,
+- never override `gt/lt` in frontend `pathFunction` with ad-hoc filters.
+
+Why:
+
+- RangeViewer computes next buckets from previous cursor boundaries,
+- replacing cursor fields causes repeated slices and broken infinite loading.
+
 ## Step 2 – Attach related objects with `.with()`
 
 Chain `.with()` calls to load related data for each item:
@@ -47,6 +60,22 @@ Each `.with()` call:
 - builds a path to the related data,
 - calls `.bind('fieldName')` to attach the result under that field name.
 
+Important:
+- this proxy is Path DSL input, not a hydrated runtime item
+- do not branch with imperative `if/else` on proxy fields inside `.with(...)`
+- for type-based conditional branches, use `$switch(...).$bind(...)`
+
+```javascript
+function settlementsPathRange(range) {
+  return path.accounting.settlementsByTransaction({ ...range })
+    .with(settlement => settlement.subjectType.$switch({
+      invoice_CostInvoice: path.invoice.costInvoice({ costInvoice: settlement.subject }),
+      invoice_IncomeInvoice: path.invoice.incomeInvoice({ incomeInvoice: settlement.subject }),
+      hr_CivilContract: path.hr.civilContract({ civilContract: settlement.subject })
+    }).$bind('subjectDoc'))
+}
+```
+
 Nested `.with()` is also supported:
 
 ```javascript
@@ -127,3 +156,64 @@ Iterate in the template:
   </div>
 </template>
 ```
+
+## Step 5 – Optional filters without breaking range cursor
+
+When your list supports optional filtering (for example `month`), do not push raw field values into `gt/gte/lt/lte` from the frontend.
+
+Why:
+
+- Range boundaries are compared against full index keys, not a single field.
+- `RangeViewer` controls `gt/lt` for pagination; overriding them breaks infinite scroll behavior.
+
+Correct pattern:
+
+1. Keep RangeViewer cursor in `range` (`...reverseRange(range)`).
+2. Send optional filters as separate params (`month`, `state`, etc.).
+3. Let backend view apply prefix logic (`sortedIndexRangePath` with longer key prefix or `App.utils.prefixRange`).
+
+```js
+function transactionsPathRange(range) {
+  return path.bankAccount.bankTransactionsByBankAccountAndDate({
+    bankAccount: accountId,
+    month: month.value || undefined,
+    ...reverseRange(range)
+  })
+}
+```
+
+## Step 6 – Reactive filter changes (no hidden bucket bugs)
+
+If `pathFunction` depends on reactive filters (for example month/company/status), prefer `ReactiveRangeViewer` over mutating `RangeViewer` input directly.
+
+Why:
+
+- changing filters can recreate bucket state in subtle ways
+- forcing rerender with ad-hoc `:key` works, but spreads fragile logic across pages
+- `ReactiveRangeViewer` centralizes safe reload behavior
+
+```vue
+<ReactiveRangeViewer
+  :pathFunction="transactionsPathRange"
+  :sourceKey="JSON.stringify({ month: filterByMonth ? month : null, accountId })"
+  :preserveHeightOnReload="true"
+  :canLoadTop="false"
+  canDropBottom
+  loadBottomSensorSize="3000px"
+  dropBottomSensorSize="8000px"
+>
+  <template #default="{ item }">
+    <BankTransactionListItem :transaction="item" />
+  </template>
+</ReactiveRangeViewer>
+```
+
+Use `sourceKey` as the explicit reload trigger when filter inputs change.
+
+## Checklist – range pagination safety
+
+- [ ] backend index view is based on `sortedIndexRangePath`
+- [ ] frontend `pathFunction` forwards `range` unchanged (`...range` or `...reverseRange(range)`)
+- [ ] domain filters (`month`, `year`, `status`) are separate view params
+- [ ] no manual cursor overrides (`gt/gte/lt/lte`) in frontend code
+- [ ] if narrowing is needed, backend uses index prefix design first, `prefixRange` only as fallback