ropegeo-common 1.16.1 → 1.17.0

package/README.md

@@ -83,23 +83,31 @@ Helper tables use columns **Name**, **Description**, **Import**. Model tables ad
 
 | Name | Base class | Description | Import |
 | --- | --- | --- | --- |
-| `DifficultyType` | N/A | Discriminator for difficulty scales (e.g. ACA). | `import { DifficultyType } from 'ropegeo-common/models'` |
-| `Difficulty` | N/A | Abstract base for page/route difficulty; `fromResult` dispatches by `difficultyType`. | `import { Difficulty } from 'ropegeo-common/models'` |
-| `registerDifficultyParser` | N/A | Registers a `Difficulty.fromResult` parser for a `DifficultyType`. | `import { registerDifficultyParser } from 'ropegeo-common/models'` |
+| `DifficultyRatingSystem` | N/A | Discriminator for difficulty rating scales (e.g. ACA). | `import { DifficultyRatingSystem } from 'ropegeo-common/models'` |
+| `DifficultyRating` | N/A | Abstract base for page/route difficulty ratings; `fromResult` dispatches by `difficultyRatingSystem`. | `import { DifficultyRating } from 'ropegeo-common/models'` |
+| `resolveDifficultyRatingFromRecord` | N/A | Reads nested difficulty rating JSON from `difficultyRating` or legacy `difficulty` keys. | `import { resolveDifficultyRatingFromRecord } from 'ropegeo-common/models'` |
+| `registerDifficultyParser` | N/A | Registers a `DifficultyRating.fromResult` parser for a `DifficultyRatingSystem`. | `import { registerDifficultyParser } from 'ropegeo-common/models'` |
 | `ACA_RISK_ORDER` | N/A | Numeric total order for ACA risk ratings. | `import { ACA_RISK_ORDER } from 'ropegeo-common/models'` |
 | `ACA_TECHNICAL_ORDER` | N/A | Numeric total order for ACA technical ratings. | `import { ACA_TECHNICAL_ORDER } from 'ropegeo-common/models'` |
 | `ACA_TIME_ORDER` | N/A | Numeric total order for ACA time ratings. | `import { ACA_TIME_ORDER } from 'ropegeo-common/models'` |
 | `ACA_WATER_ORDER` | N/A | Numeric total order for ACA water ratings. | `import { ACA_WATER_ORDER } from 'ropegeo-common/models'` |
-| `AcaTechnicalRating` | N/A | ACA technical rating enum (1–4). | `import { AcaTechnicalRating } from 'ropegeo-common/models'` |
-| `AcaWaterRating` | N/A | ACA water rating enum. | `import { AcaWaterRating } from 'ropegeo-common/models'` |
-| `AcaTimeRating` | N/A | ACA time rating enum (I–VI). | `import { AcaTimeRating } from 'ropegeo-common/models'` |
-| `AcaRiskRating` | N/A | ACA risk rating enum. | `import { AcaRiskRating } from 'ropegeo-common/models'` |
+| `AcaTechnicalSubRating` | N/A | ACA technical sub-rating enum (1–4). | `import { AcaTechnicalSubRating } from 'ropegeo-common/models'` |
+| `AcaWaterSubRating` | N/A | ACA water sub-rating enum. | `import { AcaWaterSubRating } from 'ropegeo-common/models'` |
+| `AcaTimeSubRating` | N/A | ACA time sub-rating enum (I–VI). | `import { AcaTimeSubRating } from 'ropegeo-common/models'` |
+| `AcaRiskSubRating` | N/A | ACA risk sub-rating enum. | `import { AcaRiskSubRating } from 'ropegeo-common/models'` |
 | `RISK_ORDER` | N/A | Deprecated alias for `ACA_RISK_ORDER`. | `import { RISK_ORDER } from 'ropegeo-common/models'` |
-| `AcaDifficulty` | `Difficulty` | ACA difficulty from DB/API strings; raw vs effective risk. | `import { AcaDifficulty } from 'ropegeo-common/models'` |
-| `DifficultyTechnical` | N/A | Deprecated alias for `AcaTechnicalRating`. | `import { DifficultyTechnical } from 'ropegeo-common/models'` |
-| `DifficultyWater` | N/A | Deprecated alias for `AcaWaterRating`. | `import { DifficultyWater } from 'ropegeo-common/models'` |
-| `DifficultyTime` | N/A | Deprecated alias for `AcaTimeRating`. | `import { DifficultyTime } from 'ropegeo-common/models'` |
-| `DifficultyRisk` | N/A | Deprecated alias for `AcaRiskRating`. | `import { DifficultyRisk } from 'ropegeo-common/models'` |
+| `AcaDifficultyRating` | `DifficultyRating` | ACA difficulty rating from DB/API strings; raw vs effective risk. | `import { AcaDifficultyRating } from 'ropegeo-common/models'` |
+| `DifficultyType` | N/A | Deprecated alias for `DifficultyRatingSystem`. | `import { DifficultyType } from 'ropegeo-common/models'` |
+| `Difficulty` | N/A | Deprecated alias for `DifficultyRating`. | `import { Difficulty } from 'ropegeo-common/models'` |
+| `AcaDifficulty` | N/A | Deprecated alias for `AcaDifficultyRating`. | `import { AcaDifficulty } from 'ropegeo-common/models'` |
+| `AcaTechnicalRating` | N/A | Deprecated alias for `AcaTechnicalSubRating`. | `import { AcaTechnicalRating } from 'ropegeo-common/models'` |
+| `AcaWaterRating` | N/A | Deprecated alias for `AcaWaterSubRating`. | `import { AcaWaterRating } from 'ropegeo-common/models'` |
+| `AcaTimeRating` | N/A | Deprecated alias for `AcaTimeSubRating`. | `import { AcaTimeRating } from 'ropegeo-common/models'` |
+| `AcaRiskRating` | N/A | Deprecated alias for `AcaRiskSubRating`. | `import { AcaRiskRating } from 'ropegeo-common/models'` |
+| `DifficultyTechnical` | N/A | Deprecated alias for `AcaTechnicalSubRating`. | `import { DifficultyTechnical } from 'ropegeo-common/models'` |
+| `DifficultyWater` | N/A | Deprecated alias for `AcaWaterSubRating`. | `import { DifficultyWater } from 'ropegeo-common/models'` |
+| `DifficultyTime` | N/A | Deprecated alias for `AcaTimeSubRating`. | `import { DifficultyTime } from 'ropegeo-common/models'` |
+| `DifficultyRisk` | N/A | Deprecated alias for `AcaRiskSubRating`. | `import { DifficultyRisk } from 'ropegeo-common/models'` |
 
 ### API query parameters (`src/models/api/params/`)
 
@@ -110,7 +118,7 @@ Helper tables use columns **Name**, **Description**, **Import**. Model tables ad
 | `DifficultyParams` | N/A | Abstract GET-query difficulty filter; `fromQueryStringParams` / `fromResult`. | `import { DifficultyParams } from 'ropegeo-common/models'` |
 | `DifficultyParamsQueryRecord` | N/A | Flat string map for difficulty query parsing. | `import type { DifficultyParamsQueryRecord } from 'ropegeo-common/models'` |
 | `registerDifficultyParamsQueryInference` | N/A | Registers inference when `difficulty-type` is omitted. | `import { registerDifficultyParamsQueryInference } from 'ropegeo-common/models'` |
-| `registerDifficultyParamsQueryParser` | N/A | Registers a query parser for a `DifficultyType`. | `import { registerDifficultyParamsQueryParser } from 'ropegeo-common/models'` |
+| `registerDifficultyParamsQueryParser` | N/A | Registers a query parser for a `DifficultyRatingSystem`. | `import { registerDifficultyParamsQueryParser } from 'ropegeo-common/models'` |
 | `isDifficultyParamsActive` | N/A | True if difficulty params are non-null and active. | `import { isDifficultyParamsActive } from 'ropegeo-common/models'` |
 | `AcaDifficultyParams` | `DifficultyParams` | ACA pipe-list allow-lists for routes/search query strings. | `import { AcaDifficultyParams } from 'ropegeo-common/models'` |
 | `Q_DIFFICULTY_TYPE` | N/A | Query key constant for difficulty type. | `import { Q_DIFFICULTY_TYPE } from 'ropegeo-common/models'` |
@@ -326,7 +334,7 @@ Legend entries for page minimaps are keyed objects (`legend` on `PageMiniMap`);
 
 | Name | Description | Import |
 | --- | --- | --- |
-| `RopeGeoDataLoader` | Single-request loader: `onlinePath` / `onlinePathParams`, optional `offlineData` (object used as `data` immediately; no network), optional `timeoutAfterSeconds` and `isOnline`. Children receive `data`, `errors`, `timeoutCountdown` (numeric only while an online fetch is in flight, otherwise `null`), and `reload`. Reconnect refetch uses `dirtyWhileOffline` driven by a semantic key (no `refreshOnReconnect` prop). Also exports `Method`, `Service`, `SERVICE_BASE_URL`. | `import { RopeGeoDataLoader, Method, Service } from 'ropegeo-common/components'` |
+| `RopeGeoDataLoader` | Single-request loader: `onlinePath` / `onlinePathParams`, optional `offlineData` (`undefined` → fetch online; `null` → `data` null / loading-style, no fetch; `T` → use as `data`, no fetch), optional `timeoutAfterSeconds` and `isOnline`. Children receive `data`, `errors`, `timeoutCountdown` (numeric only while an online fetch is in flight, otherwise `null`), and `reload`. Reconnect refetch uses `dirtyWhileOffline` driven by a semantic key (no `refreshOnReconnect` prop). Also exports `Method`, `Service`, `SERVICE_BASE_URL`. | `import { RopeGeoDataLoader, Method, Service } from 'ropegeo-common/components'` |
 | `RopeGeoPagedDataLoader` | Cursor-paginated list: same networking props as above; children get `loadNextPage`, `loadingNextPage`, `morePages`, plus `data`, `errors`, `timeoutCountdown`, `reload`. | `import { RopeGeoPagedDataLoader } from 'ropegeo-common/components'` |
 | `RopeGeoProgressDataLoader` | Page-based “progress” fetch: batches additional pages until `total` is satisfied; children get `received`, `total`, `data`, `errors`, `timeoutCountdown`, `reload`. | `import { RopeGeoProgressDataLoader } from 'ropegeo-common/components'` |
 

package/dist/components/RopeGeoDataLoader.d.ts

@@ -31,10 +31,12 @@ export type RopeGeoDataLoaderProps<T = unknown> = {
      */
     isOnline?: boolean;
     /**
-     * When set, this value is used as `data` immediately (no network). Callers that load from disk
-     * should read and parse the file themselves, then pass the resulting object here.
+     * Offline / local-first behavior without reading files inside the loader:
+     * - **`undefined`**: omit or leave unset — fetch from {@link onlinePath} as usual.
+     * - **`null`**: do not fetch; children receive `data: null` and `errors: null` (loading-style).
+     * - **`T`**: use as `data` immediately; no network.
      */
-    offlineData?: T;
+    offlineData?: T | null;
     children: (args: {
         data: T | null;
         errors: Error | null;

package/dist/components/RopeGeoDataLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RopeGeoDataLoader.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoDataLoader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAavC,eAAO,MAAM,OAAO;;CAEV,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAEpD,CAAC;AAoEF,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB;;;WAGG;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,iFAAiF;QACjF,MAAM,EAAE,MAAM,IAAI,CAAC;KACpB,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC7C,OAAO,EACP,MAAM,EACN,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,WAAW,EACX,QAAQ,GACT,EAAE,sBAAsB,CAAC,CAAC,CAAC,2CAwT3B"}
+{"version":3,"file":"RopeGeoDataLoader.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoDataLoader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAavC,eAAO,MAAM,OAAO;;CAEV,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAEpD,CAAC;AAqEF,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB;;;WAGG;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,iFAAiF;QACjF,MAAM,EAAE,MAAM,IAAI,CAAC;KACpB,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC7C,OAAO,EACP,MAAM,EACN,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,WAAW,EACX,QAAQ,GACT,EAAE,sBAAsB,CAAC,CAAC,CAAC,2CAgU3B"}

package/dist/components/RopeGeoDataLoader.js

@@ -57,6 +57,8 @@ function dataLoaderReconnectSemanticKey(service, method, onlinePath, pathParamsK
 function offlineDataKeyPart(offlineData) {
     if (offlineData === undefined)
         return "";
+    if (offlineData === null)
+        return "|offline:null";
     return `|obj:${JSON.stringify(offlineData)}`;
 }
 function RopeGeoDataLoader({ service, method, onlinePath, onlinePathParams, queryParams, body, timeoutAfterSeconds, isOnline, offlineData, children, }) {
@@ -104,11 +106,19 @@ function RopeGeoDataLoader({ service, method, onlinePath, onlinePathParams, quer
         setReloadTick((n) => n + 1);
     }, [isOnline]);
     const lastRequestKeyRef = (0, react_1.useRef)("");
-    /** `offlineData` object — immediate `data`, no network. */
+    /** Sync `data` from {@link offlineData} when it is `null` or `T`; `undefined` defers to the network effect. */
     (0, react_1.useEffect)(() => {
         if (offlineData === undefined) {
             return;
         }
+        if (offlineData === null) {
+            setData(null);
+            setErrors(null);
+            hasCommittedRef.current = false;
+            dirtyWhileOfflineRef.current = false;
+            semanticSnapshotRef.current = null;
+            return;
+        }
         setData(offlineData);
         setErrors(null);
         hasCommittedRef.current = true;
@@ -130,7 +140,7 @@ function RopeGeoDataLoader({ service, method, onlinePath, onlinePathParams, quer
                 dirtyWhileOfflineRef.current = true;
             }
         }
-        /** Object `offlineData`: dedicated effect owns `data`; never hit the network here. */
+        /** `offlineData` is `null` or `T`: own `data`; never hit the network here. */
         if (offlineData !== undefined) {
             prevIsOnlineRef.current = online;
             return;

package/dist/models/api/params/acaDifficultyParams.d.ts

@@ -1,5 +1,5 @@
-import { DifficultyType } from '../../difficulty/difficulty';
-import { AcaRiskRating, AcaTechnicalRating, AcaTimeRating, AcaWaterRating } from '../../difficulty/acaRatings';
+import { DifficultyRatingSystem } from '../../difficulty/difficultyRating';
+import { AcaRiskSubRating, AcaTechnicalSubRating, AcaTimeSubRating, AcaWaterSubRating } from '../../difficulty/acaSubRatings';
 import { DifficultyParams, type DifficultyParamsQueryRecord } from './difficultyParams';
 export declare const Q_DIFFICULTY_TYPE = "difficulty-type";
 export declare const Q_ACA_TECHNICAL = "aca-technical-rating";
@@ -7,12 +7,12 @@ export declare const Q_ACA_WATER = "aca-water-rating";
 export declare const Q_ACA_TIME = "aca-time-rating";
 export declare const Q_ACA_RISK = "aca-risk-rating";
 export declare class AcaDifficultyParams extends DifficultyParams {
-    readonly difficultyType = DifficultyType.ACA;
-    readonly technical: AcaTechnicalRating[];
-    readonly water: AcaWaterRating[];
-    readonly time: AcaTimeRating[];
-    readonly effectiveRisk: AcaRiskRating[];
-    constructor(technical: AcaTechnicalRating[], water: AcaWaterRating[], time: AcaTimeRating[], effectiveRisk: AcaRiskRating[]);
+    readonly difficultyType = DifficultyRatingSystem.ACA;
+    readonly technical: AcaTechnicalSubRating[];
+    readonly water: AcaWaterSubRating[];
+    readonly time: AcaTimeSubRating[];
+    readonly effectiveRisk: AcaRiskSubRating[];
+    constructor(technical: AcaTechnicalSubRating[], water: AcaWaterSubRating[], time: AcaTimeSubRating[], effectiveRisk: AcaRiskSubRating[]);
     isActive(): boolean;
     toQueryString(): string;
     static fromQueryStringParams(q: DifficultyParamsQueryRecord): AcaDifficultyParams;

package/dist/models/api/params/acaDifficultyParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acaDifficultyParams.d.ts","sourceRoot":"","sources":["../../../../src/models/api/params/acaDifficultyParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EACH,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,cAAc,EACjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACH,gBAAgB,EAChB,KAAK,2BAA2B,EAGnC,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,eAAO,MAAM,eAAe,yBAAyB,CAAC;AACtD,eAAO,MAAM,WAAW,qBAAqB,CAAC;AAC9C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAC5C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AA8C5C,qBAAa,mBAAoB,SAAQ,gBAAgB;IACrD,QAAQ,CAAC,cAAc,sBAAsB;IAE7C,QAAQ,CAAC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,EAAE,CAAC;gBAGpC,SAAS,EAAE,kBAAkB,EAAE,EAC/B,KAAK,EAAE,cAAc,EAAE,EACvB,IAAI,EAAE,aAAa,EAAE,EACrB,aAAa,EAAE,aAAa,EAAE;IASlC,QAAQ,IAAI,OAAO;IASnB,aAAa,IAAI,MAAM;IAwBvB,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,2BAA2B,GAC/B,mBAAmB;IAwBtB,OAAO,CAAC,MAAM,CAAC,cAAc;IAW7B,uFAAuF;IACvF,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IAgCpE,kEAAkE;IAClE,MAAM,CAAC,cAAc,CACjB,MAAM,EAAE,mBAAmB,GAAG,IAAI,GACnC,mBAAmB,GAAG,IAAI;CAIhC"}
+{"version":3,"file":"acaDifficultyParams.d.ts","sourceRoot":"","sources":["../../../../src/models/api/params/acaDifficultyParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACH,gBAAgB,EAChB,KAAK,2BAA2B,EAGnC,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,eAAO,MAAM,eAAe,yBAAyB,CAAC;AACtD,eAAO,MAAM,WAAW,qBAAqB,CAAC;AAC9C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAC5C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AA8C5C,qBAAa,mBAAoB,SAAQ,gBAAgB;IACrD,QAAQ,CAAC,cAAc,8BAA8B;IAErD,QAAQ,CAAC,SAAS,EAAE,qBAAqB,EAAE,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,gBAAgB,EAAE,CAAC;gBAGvC,SAAS,EAAE,qBAAqB,EAAE,EAClC,KAAK,EAAE,iBAAiB,EAAE,EAC1B,IAAI,EAAE,gBAAgB,EAAE,EACxB,aAAa,EAAE,gBAAgB,EAAE;IASrC,QAAQ,IAAI,OAAO;IASnB,aAAa,IAAI,MAAM;IAwBvB,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,2BAA2B,GAC/B,mBAAmB;IAwBtB,OAAO,CAAC,MAAM,CAAC,cAAc;IAW7B,uFAAuF;IACvF,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB;IAgCpE,kEAAkE;IAClE,MAAM,CAAC,cAAc,CACjB,MAAM,EAAE,mBAAmB,GAAG,IAAI,GACnC,mBAAmB,GAAG,IAAI;CAIhC"}

package/dist/models/api/params/acaDifficultyParams.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AcaDifficultyParams = exports.Q_ACA_RISK = exports.Q_ACA_TIME = exports.Q_ACA_WATER = exports.Q_ACA_TECHNICAL = exports.Q_DIFFICULTY_TYPE = void 0;
-const difficulty_1 = require("../../difficulty/difficulty");
-const acaRatings_1 = require("../../difficulty/acaRatings");
+const difficultyRating_1 = require("../../difficulty/difficultyRating");
+const acaSubRatings_1 = require("../../difficulty/acaSubRatings");
 const difficultyParams_1 = require("./difficultyParams");
 exports.Q_DIFFICULTY_TYPE = 'difficulty-type';
 exports.Q_ACA_TECHNICAL = 'aca-technical-rating';
@@ -45,7 +45,7 @@ function acaAxisKeysPresent(q) {
 class AcaDifficultyParams extends difficultyParams_1.DifficultyParams {
     constructor(technical, water, time, effectiveRisk) {
         super();
-        this.difficultyType = difficulty_1.DifficultyType.ACA;
+        this.difficultyType = difficultyRating_1.DifficultyRatingSystem.ACA;
         this.technical = [...technical];
         this.water = [...water];
         this.time = [...time];
@@ -75,10 +75,10 @@ class AcaDifficultyParams extends difficultyParams_1.DifficultyParams {
         return p.toString();
     }
     static fromQueryStringParams(q) {
-        const technical = parseEnumTokens(q[exports.Q_ACA_TECHNICAL] ?? q['Aca-Technical-Rating'], Object.values(acaRatings_1.AcaTechnicalRating), 'aca-technical-rating');
-        const water = parseEnumTokens(q[exports.Q_ACA_WATER] ?? q['Aca-Water-Rating'], Object.values(acaRatings_1.AcaWaterRating), 'aca-water-rating');
-        const time = parseEnumTokens(q[exports.Q_ACA_TIME] ?? q['Aca-Time-Rating'], Object.values(acaRatings_1.AcaTimeRating), 'aca-time-rating');
-        const effectiveRisk = parseEnumTokens(q[exports.Q_ACA_RISK] ?? q['Aca-Risk-Rating'], Object.values(acaRatings_1.AcaRiskRating), 'aca-risk-rating');
+        const technical = parseEnumTokens(q[exports.Q_ACA_TECHNICAL] ?? q['Aca-Technical-Rating'], Object.values(acaSubRatings_1.AcaTechnicalSubRating), 'aca-technical-rating');
+        const water = parseEnumTokens(q[exports.Q_ACA_WATER] ?? q['Aca-Water-Rating'], Object.values(acaSubRatings_1.AcaWaterSubRating), 'aca-water-rating');
+        const time = parseEnumTokens(q[exports.Q_ACA_TIME] ?? q['Aca-Time-Rating'], Object.values(acaSubRatings_1.AcaTimeSubRating), 'aca-time-rating');
+        const effectiveRisk = parseEnumTokens(q[exports.Q_ACA_RISK] ?? q['Aca-Risk-Rating'], Object.values(acaSubRatings_1.AcaRiskSubRating), 'aca-risk-rating');
         return new AcaDifficultyParams(technical, water, time, effectiveRisk);
     }
     static optionalString(obj, ...keys) {
@@ -91,10 +91,10 @@ class AcaDifficultyParams extends difficultyParams_1.DifficultyParams {
     }
     /** Parses JSON objects with the same key variants as {@link fromQueryStringParams}. */
     static fromResult(obj) {
-        const technical = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_TECHNICAL, 'Aca-Technical-Rating'), Object.values(acaRatings_1.AcaTechnicalRating), 'aca-technical-rating');
-        const water = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_WATER, 'Aca-Water-Rating'), Object.values(acaRatings_1.AcaWaterRating), 'aca-water-rating');
-        const time = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_TIME, 'Aca-Time-Rating'), Object.values(acaRatings_1.AcaTimeRating), 'aca-time-rating');
-        const effectiveRisk = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_RISK, 'Aca-Risk-Rating'), Object.values(acaRatings_1.AcaRiskRating), 'aca-risk-rating');
+        const technical = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_TECHNICAL, 'Aca-Technical-Rating'), Object.values(acaSubRatings_1.AcaTechnicalSubRating), 'aca-technical-rating');
+        const water = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_WATER, 'Aca-Water-Rating'), Object.values(acaSubRatings_1.AcaWaterSubRating), 'aca-water-rating');
+        const time = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_TIME, 'Aca-Time-Rating'), Object.values(acaSubRatings_1.AcaTimeSubRating), 'aca-time-rating');
+        const effectiveRisk = parseEnumTokens(AcaDifficultyParams.optionalString(obj, exports.Q_ACA_RISK, 'Aca-Risk-Rating'), Object.values(acaSubRatings_1.AcaRiskSubRating), 'aca-risk-rating');
         return new AcaDifficultyParams(technical, water, time, effectiveRisk);
     }
     /** Returns null if every axis is empty (no difficulty filter). */
@@ -105,5 +105,5 @@ class AcaDifficultyParams extends difficultyParams_1.DifficultyParams {
     }
 }
 exports.AcaDifficultyParams = AcaDifficultyParams;
-(0, difficultyParams_1.registerDifficultyParamsQueryInference)((q) => acaAxisKeysPresent(q) ? difficulty_1.DifficultyType.ACA : null);
-(0, difficultyParams_1.registerDifficultyParamsQueryParser)(difficulty_1.DifficultyType.ACA, (q) => AcaDifficultyParams.fromQueryStringParams(q));
+(0, difficultyParams_1.registerDifficultyParamsQueryInference)((q) => acaAxisKeysPresent(q) ? difficultyRating_1.DifficultyRatingSystem.ACA : null);
+(0, difficultyParams_1.registerDifficultyParamsQueryParser)(difficultyRating_1.DifficultyRatingSystem.ACA, (q) => AcaDifficultyParams.fromQueryStringParams(q));

package/dist/models/api/params/difficultyParams.d.ts

@@ -1,16 +1,16 @@
-import { DifficultyType } from '../../difficulty/difficulty';
+import { DifficultyRatingSystem } from '../../difficulty/difficultyRating';
 /** Flat query / query-like record for {@link DifficultyParams.fromQueryStringParams}. */
 export type DifficultyParamsQueryRecord = Record<string, string | undefined>;
 /**
- * When `difficulty-type` is absent, this hook may return a {@link DifficultyType} to parse with
+ * When `difficulty-type` is absent, this hook may return a {@link DifficultyRatingSystem} to parse with
  * {@link registerDifficultyParamsQueryParser} (e.g. ACA when any `aca-*-rating` key is present).
  */
-export declare function registerDifficultyParamsQueryInference(fn: (q: DifficultyParamsQueryRecord) => DifficultyType | null): void;
+export declare function registerDifficultyParamsQueryInference(fn: (q: DifficultyParamsQueryRecord) => DifficultyRatingSystem | null): void;
 /**
  * Registers the parser for {@link DifficultyParams.fromQueryStringParams} for a given type
  * (see `registerDifficultyParamsParsers.ts`).
  */
-export declare function registerDifficultyParamsQueryParser(type: DifficultyType, parse: (q: DifficultyParamsQueryRecord) => DifficultyParams): void;
+export declare function registerDifficultyParamsQueryParser(type: DifficultyRatingSystem, parse: (q: DifficultyParamsQueryRecord) => DifficultyParams): void;
 /**
  * Registers {@link DifficultyParams.fromResult} (see `registerDifficultyParamsParsers.ts`).
  */
@@ -19,7 +19,7 @@ export declare function registerDifficultyParamsResultParser(parse: (result: unk
  * Query serialization for GET /routes and GET /search difficulty filters.
  */
 export declare abstract class DifficultyParams {
-    abstract readonly difficultyType: DifficultyType;
+    abstract readonly difficultyType: DifficultyRatingSystem;
     abstract toQueryString(): string;
     abstract isActive(): boolean;
     /**

package/dist/models/api/params/difficultyParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"difficultyParams.d.ts","sourceRoot":"","sources":["../../../../src/models/api/params/difficultyParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,yFAAyF;AACzF,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAe7E;;;GAGG;AACH,wBAAgB,sCAAsC,CAClD,EAAE,EAAE,CAAC,CAAC,EAAE,2BAA2B,KAAK,cAAc,GAAG,IAAI,GAC9D,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CAC/C,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,CAAC,CAAC,EAAE,2BAA2B,KAAK,gBAAgB,GAC5D,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CAChD,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,gBAAgB,GAAG,IAAI,GACpD,IAAI,CAEN;AAED;;GAEG;AACH,8BAAsB,gBAAgB;IAClC,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAEjD,QAAQ,CAAC,aAAa,IAAI,MAAM;IAEhC,QAAQ,CAAC,QAAQ,IAAI,OAAO;IAE5B;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,2BAA2B,GAC/B,gBAAgB,GAAG,IAAI;IAmC1B;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI;IAS3D,8FAA8F;IAC9F,MAAM,CAAC,uBAAuB,CAC1B,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,gBAAgB,GAAG,IAAI,GACpC,IAAI;CAOV;AAED,wBAAgB,wBAAwB,CACpC,CAAC,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACvC,OAAO,CAET"}
+{"version":3,"file":"difficultyParams.d.ts","sourceRoot":"","sources":["../../../../src/models/api/params/difficultyParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE3E,yFAAyF;AACzF,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAe7E;;;GAGG;AACH,wBAAgB,sCAAsC,CAClD,EAAE,EAAE,CAAC,CAAC,EAAE,2BAA2B,KAAK,sBAAsB,GAAG,IAAI,GACtE,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CAC/C,IAAI,EAAE,sBAAsB,EAC5B,KAAK,EAAE,CAAC,CAAC,EAAE,2BAA2B,KAAK,gBAAgB,GAC5D,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,oCAAoC,CAChD,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,gBAAgB,GAAG,IAAI,GACpD,IAAI,CAEN;AAED;;GAEG;AACH,8BAAsB,gBAAgB;IAClC,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,sBAAsB,CAAC;IAEzD,QAAQ,CAAC,aAAa,IAAI,MAAM;IAEhC,QAAQ,CAAC,QAAQ,IAAI,OAAO;IAE5B;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,2BAA2B,GAC/B,gBAAgB,GAAG,IAAI;IAmC1B;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI;IAS3D,8FAA8F;IAC9F,MAAM,CAAC,uBAAuB,CAC1B,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,gBAAgB,GAAG,IAAI,GACpC,IAAI;CAOV;AAED,wBAAgB,wBAAwB,CACpC,CAAC,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACvC,OAAO,CAET"}

package/dist/models/api/params/difficultyParams.js

@@ -5,12 +5,12 @@ exports.registerDifficultyParamsQueryInference = registerDifficultyParamsQueryIn
 exports.registerDifficultyParamsQueryParser = registerDifficultyParamsQueryParser;
 exports.registerDifficultyParamsResultParser = registerDifficultyParamsResultParser;
 exports.isDifficultyParamsActive = isDifficultyParamsActive;
-const difficulty_1 = require("../../difficulty/difficulty");
+const difficultyRating_1 = require("../../difficulty/difficultyRating");
 const queryParsers = new Map();
 let queryInference;
 let parseFromResult;
 /**
- * When `difficulty-type` is absent, this hook may return a {@link DifficultyType} to parse with
+ * When `difficulty-type` is absent, this hook may return a {@link DifficultyRatingSystem} to parse with
  * {@link registerDifficultyParamsQueryParser} (e.g. ACA when any `aca-*-rating` key is present).
  */
 function registerDifficultyParamsQueryInference(fn) {
@@ -55,7 +55,7 @@ class DifficultyParams {
             return parser(q);
         }
         if (rawType === 'aca') {
-            const parser = queryParsers.get(difficulty_1.DifficultyType.ACA);
+            const parser = queryParsers.get(difficultyRating_1.DifficultyRatingSystem.ACA);
             if (parser === undefined) {
                 throw new Error('No difficulty params query parser registered for difficultyType ACA');
             }

package/dist/models/difficulty/acaDifficultyRating.d.ts

@@ -0,0 +1,31 @@
+import { DifficultyRating, DifficultyRatingSystem } from './difficultyRating';
+import { AcaRiskSubRating, AcaTechnicalSubRating, AcaTimeSubRating, AcaWaterSubRating } from './acaSubRatings';
+/**
+ * ACA canyon difficulty rating from DB strings. `additionalRisk` is the raw stored value
+ * (`riskRating` column); `effectiveRisk` applies the technical default floor when `additionalRisk`
+ * is null or milder than that default.
+ */
+export declare class AcaDifficultyRating extends DifficultyRating {
+    readonly difficultyRatingSystem = DifficultyRatingSystem.ACA;
+    readonly technical: AcaTechnicalSubRating | null;
+    readonly water: AcaWaterSubRating | null;
+    readonly time: AcaTimeSubRating | null;
+    /** Raw additional risk from ropewiki (`riskRating` column), after enum parse; null if unset. */
+    readonly additionalRisk: AcaRiskSubRating | null;
+    /** Risk used for display and sorting (never milder than the default implied by technical). */
+    readonly effectiveRisk: AcaRiskSubRating | null;
+    constructor(technicalRating: string | null | undefined, waterRating: string | null | undefined, timeRating: string | null | undefined, additionalRiskRating: string | null | undefined);
+    getEffectiveRiskForDisplay(): AcaRiskSubRating | null;
+    private static assignParts;
+    private static defaultRiskFromTechnical;
+    private static computeEffectiveRisk;
+    private static parseField;
+    /**
+     * Parses JSON/API objects: `difficultyRatingSystem: 'ACA'` (optional when dispatched via
+     * {@link DifficultyRating.fromResult}), `technical`, `water`, `time`, `additionalRisk` (raw),
+     * optional `effectiveRisk` override. Legacy `difficultyType` is accepted.
+     */
+    static fromResult(result: unknown): AcaDifficultyRating;
+    private static coerceOptionalString;
+}
+//# sourceMappingURL=acaDifficultyRating.d.ts.map

package/dist/models/difficulty/acaDifficultyRating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acaDifficultyRating.d.ts","sourceRoot":"","sources":["../../../src/models/difficulty/acaDifficultyRating.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EAEzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEH,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACpB,MAAM,iBAAiB,CAAC;AAUzB;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;IACrD,QAAQ,CAAC,sBAAsB,8BAA8B;IAE7D,QAAQ,CAAC,SAAS,EAAG,qBAAqB,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAG,iBAAiB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAG,gBAAgB,GAAG,IAAI,CAAC;IACxC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,EAAG,gBAAgB,GAAG,IAAI,CAAC;IAClD,8FAA8F;IAC9F,QAAQ,CAAC,aAAa,EAAG,gBAAgB,GAAG,IAAI,CAAC;gBAG7C,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC1C,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,oBAAoB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAoCnD,0BAA0B,IAAI,gBAAgB,GAAG,IAAI;IAIrD,OAAO,CAAC,MAAM,CAAC,WAAW;IAa1B,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAcvC,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAcnC,OAAO,CAAC,MAAM,CAAC,UAAU;IAezB;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,mBAAmB;IA6CvD,OAAO,CAAC,MAAM,CAAC,oBAAoB;CAOtC"}

package/dist/models/difficulty/acaDifficultyRating.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AcaDifficultyRating = void 0;
+const difficultyRating_1 = require("./difficultyRating");
+const acaSubRatings_1 = require("./acaSubRatings");
+/**
+ * ACA canyon difficulty rating from DB strings. `additionalRisk` is the raw stored value
+ * (`riskRating` column); `effectiveRisk` applies the technical default floor when `additionalRisk`
+ * is null or milder than that default.
+ */
+class AcaDifficultyRating extends difficultyRating_1.DifficultyRating {
+    constructor(technicalRating, waterRating, timeRating, additionalRiskRating) {
+        super();
+        this.difficultyRatingSystem = difficultyRating_1.DifficultyRatingSystem.ACA;
+        const technical = AcaDifficultyRating.parseField(technicalRating, Object.values(acaSubRatings_1.AcaTechnicalSubRating), 'technical');
+        const water = AcaDifficultyRating.parseField(waterRating, Object.values(acaSubRatings_1.AcaWaterSubRating), 'water');
+        const time = AcaDifficultyRating.parseField(timeRating, Object.values(acaSubRatings_1.AcaTimeSubRating), 'time');
+        const parsedAdditionalRisk = AcaDifficultyRating.parseField(additionalRiskRating, Object.values(acaSubRatings_1.AcaRiskSubRating), 'additionalRisk');
+        const parts = {
+            technical,
+            water,
+            time,
+            additionalRisk: parsedAdditionalRisk,
+            effectiveRisk: AcaDifficultyRating.computeEffectiveRisk(parsedAdditionalRisk, technical),
+        };
+        AcaDifficultyRating.assignParts(this, parts);
+    }
+    getEffectiveRiskForDisplay() {
+        return this.effectiveRisk;
+    }
+    static assignParts(target, parts) {
+        target.technical = parts.technical;
+        target.water = parts.water;
+        target.time = parts.time;
+        target.additionalRisk =
+            parts.additionalRisk;
+        target.effectiveRisk =
+            parts.effectiveRisk;
+    }
+    static defaultRiskFromTechnical(technical) {
+        if (technical === acaSubRatings_1.AcaTechnicalSubRating.One)
+            return acaSubRatings_1.AcaRiskSubRating.G;
+        if (technical === acaSubRatings_1.AcaTechnicalSubRating.Two)
+            return acaSubRatings_1.AcaRiskSubRating.PG;
+        if (technical === acaSubRatings_1.AcaTechnicalSubRating.Three ||
+            technical === acaSubRatings_1.AcaTechnicalSubRating.Four) {
+            return acaSubRatings_1.AcaRiskSubRating.PG13;
+        }
+        return null;
+    }
+    static computeEffectiveRisk(additionalRisk, technical) {
+        const defaultRisk = AcaDifficultyRating.defaultRiskFromTechnical(technical);
+        if (additionalRisk != null) {
+            return defaultRisk != null &&
+                acaSubRatings_1.ACA_RISK_ORDER[additionalRisk] < acaSubRatings_1.ACA_RISK_ORDER[defaultRisk]
+                ? defaultRisk
+                : additionalRisk;
+        }
+        return defaultRisk;
+    }
+    static parseField(value, allowed, fieldName) {
+        if (value == null || value === '')
+            return null;
+        const trimmed = value.trim();
+        if (!allowed.includes(trimmed)) {
+            throw new Error(`Invalid difficulty ${fieldName}: "${value}" is not one of [${allowed.join(', ')}]`);
+        }
+        return trimmed;
+    }
+    /**
+     * Parses JSON/API objects: `difficultyRatingSystem: 'ACA'` (optional when dispatched via
+     * {@link DifficultyRating.fromResult}), `technical`, `water`, `time`, `additionalRisk` (raw),
+     * optional `effectiveRisk` override. Legacy `difficultyType` is accepted.
+     */
+    static fromResult(result) {
+        if (result == null || typeof result !== 'object') {
+            throw new Error('AcaDifficultyRating result must be an object');
+        }
+        const r = result;
+        const dtype = r.difficultyRatingSystem ??
+            r.DifficultyRatingSystem ??
+            r.difficultyType ??
+            r.DifficultyType;
+        if (dtype !== undefined &&
+            dtype !== null &&
+            typeof dtype === 'string' &&
+            dtype.toUpperCase() !== difficultyRating_1.DifficultyRatingSystem.ACA) {
+            throw new Error(`Unsupported difficultyRatingSystem for AcaDifficultyRating.fromResult: ${JSON.stringify(dtype)}`);
+        }
+        const tech = AcaDifficultyRating.coerceOptionalString(r.technical ?? r.Technical);
+        const water = AcaDifficultyRating.coerceOptionalString(r.water ?? r.Water);
+        const time = AcaDifficultyRating.coerceOptionalString(r.time ?? r.Time);
+        const additionalRiskRaw = AcaDifficultyRating.coerceOptionalString(r.additionalRisk ?? r.AdditionalRisk);
+        const effectiveRaw = AcaDifficultyRating.coerceOptionalString(r.effectiveRisk ?? r.EffectiveRisk);
+        if (effectiveRaw !== null) {
+            const inst = new AcaDifficultyRating(tech, water, time, additionalRiskRaw);
+            const effParsed = AcaDifficultyRating.parseField(effectiveRaw, Object.values(acaSubRatings_1.AcaRiskSubRating), 'effectiveRisk');
+            inst.effectiveRisk = effParsed;
+            return inst;
+        }
+        return new AcaDifficultyRating(tech, water, time, additionalRiskRaw);
+    }
+    static coerceOptionalString(v) {
+        if (v === undefined || v === null || v === '')
+            return null;
+        if (typeof v !== 'string') {
+            throw new Error('AcaDifficultyRating field must be string or null');
+        }
+        return v;
+    }
+}
+exports.AcaDifficultyRating = AcaDifficultyRating;
+(0, difficultyRating_1.registerDifficultyParser)(difficultyRating_1.DifficultyRatingSystem.ACA, (v) => AcaDifficultyRating.fromResult(v));

package/dist/models/difficulty/{acaRatings.d.ts → acaSubRatings.d.ts}

@@ -1,12 +1,12 @@
 /** ACA technical rating: 1–4 */
-export declare enum AcaTechnicalRating {
+export declare enum AcaTechnicalSubRating {
     One = "1",
     Two = "2",
     Three = "3",
     Four = "4"
 }
 /** ACA water rating: A, B, C, or C1–C4 */
-export declare enum AcaWaterRating {
+export declare enum AcaWaterSubRating {
     A = "A",
     B = "B",
     C = "C",
@@ -16,7 +16,7 @@ export declare enum AcaWaterRating {
     C4 = "C4"
 }
 /** ACA time rating: I–VI */
-export declare enum AcaTimeRating {
+export declare enum AcaTimeSubRating {
     I = "I",
     II = "II",
     III = "III",
@@ -25,7 +25,7 @@ export declare enum AcaTimeRating {
     VI = "VI"
 }
 /** ACA risk rating */
-export declare enum AcaRiskRating {
+export declare enum AcaRiskSubRating {
     G = "G",
     PG = "PG",
     PG13 = "PG13",
@@ -34,12 +34,12 @@ export declare enum AcaRiskRating {
     XX = "XX"
 }
 /** Total order for technical (lower index = easier). */
-export declare const ACA_TECHNICAL_ORDER: Record<AcaTechnicalRating, number>;
+export declare const ACA_TECHNICAL_ORDER: Record<AcaTechnicalSubRating, number>;
 /** Total order for water: A < B < C < C1 < C2 < C3 < C4 */
-export declare const ACA_WATER_ORDER: Record<AcaWaterRating, number>;
-export declare const ACA_TIME_ORDER: Record<AcaTimeRating, number>;
+export declare const ACA_WATER_ORDER: Record<AcaWaterSubRating, number>;
+export declare const ACA_TIME_ORDER: Record<AcaTimeSubRating, number>;
 /** Lower index = milder risk */
-export declare const ACA_RISK_ORDER: Record<AcaRiskRating, number>;
+export declare const ACA_RISK_ORDER: Record<AcaRiskSubRating, number>;
 /** @deprecated Use ACA_RISK_ORDER */
-export declare const RISK_ORDER: Record<AcaRiskRating, number>;
-//# sourceMappingURL=acaRatings.d.ts.map
+export declare const RISK_ORDER: Record<AcaRiskSubRating, number>;
+//# sourceMappingURL=acaSubRatings.d.ts.map

package/dist/models/difficulty/acaSubRatings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acaSubRatings.d.ts","sourceRoot":"","sources":["../../../src/models/difficulty/acaSubRatings.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,oBAAY,qBAAqB;IAC7B,GAAG,MAAM;IACT,GAAG,MAAM;IACT,KAAK,MAAM;IACX,IAAI,MAAM;CACb;AAED,0CAA0C;AAC1C,oBAAY,iBAAiB;IACzB,CAAC,MAAM;IACP,CAAC,MAAM;IACP,CAAC,MAAM;IACP,EAAE,OAAO;IACT,EAAE,OAAO;IACT,EAAE,OAAO;IACT,EAAE,OAAO;CACZ;AAED,4BAA4B;AAC5B,oBAAY,gBAAgB;IACxB,CAAC,MAAM;IACP,EAAE,OAAO;IACT,GAAG,QAAQ;IACX,EAAE,OAAO;IACT,CAAC,MAAM;IACP,EAAE,OAAO;CACZ;AAED,sBAAsB;AACtB,oBAAY,gBAAgB;IACxB,CAAC,MAAM;IACP,EAAE,OAAO;IACT,IAAI,SAAS;IACb,CAAC,MAAM;IACP,CAAC,MAAM;IACP,EAAE,OAAO;CACZ;AAED,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAKrE,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAQ7D,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAO3D,CAAC;AAEF,gCAAgC;AAChC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAO3D,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,UAAU,kCAAiB,CAAC"}

package/dist/models/difficulty/acaSubRatings.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RISK_ORDER = exports.ACA_RISK_ORDER = exports.ACA_TIME_ORDER = exports.ACA_WATER_ORDER = exports.ACA_TECHNICAL_ORDER = exports.AcaRiskSubRating = exports.AcaTimeSubRating = exports.AcaWaterSubRating = exports.AcaTechnicalSubRating = void 0;
+/** ACA technical rating: 1–4 */
+var AcaTechnicalSubRating;
+(function (AcaTechnicalSubRating) {
+    AcaTechnicalSubRating["One"] = "1";
+    AcaTechnicalSubRating["Two"] = "2";
+    AcaTechnicalSubRating["Three"] = "3";
+    AcaTechnicalSubRating["Four"] = "4";
+})(AcaTechnicalSubRating || (exports.AcaTechnicalSubRating = AcaTechnicalSubRating = {}));
+/** ACA water rating: A, B, C, or C1–C4 */
+var AcaWaterSubRating;
+(function (AcaWaterSubRating) {
+    AcaWaterSubRating["A"] = "A";
+    AcaWaterSubRating["B"] = "B";
+    AcaWaterSubRating["C"] = "C";
+    AcaWaterSubRating["C1"] = "C1";
+    AcaWaterSubRating["C2"] = "C2";
+    AcaWaterSubRating["C3"] = "C3";
+    AcaWaterSubRating["C4"] = "C4";
+})(AcaWaterSubRating || (exports.AcaWaterSubRating = AcaWaterSubRating = {}));
+/** ACA time rating: I–VI */
+var AcaTimeSubRating;
+(function (AcaTimeSubRating) {
+    AcaTimeSubRating["I"] = "I";
+    AcaTimeSubRating["II"] = "II";
+    AcaTimeSubRating["III"] = "III";
+    AcaTimeSubRating["IV"] = "IV";
+    AcaTimeSubRating["V"] = "V";
+    AcaTimeSubRating["VI"] = "VI";
+})(AcaTimeSubRating || (exports.AcaTimeSubRating = AcaTimeSubRating = {}));
+/** ACA risk rating */
+var AcaRiskSubRating;
+(function (AcaRiskSubRating) {
+    AcaRiskSubRating["G"] = "G";
+    AcaRiskSubRating["PG"] = "PG";
+    AcaRiskSubRating["PG13"] = "PG13";
+    AcaRiskSubRating["R"] = "R";
+    AcaRiskSubRating["X"] = "X";
+    AcaRiskSubRating["XX"] = "XX";
+})(AcaRiskSubRating || (exports.AcaRiskSubRating = AcaRiskSubRating = {}));
+/** Total order for technical (lower index = easier). */
+exports.ACA_TECHNICAL_ORDER = {
+    [AcaTechnicalSubRating.One]: 0,
+    [AcaTechnicalSubRating.Two]: 1,
+    [AcaTechnicalSubRating.Three]: 2,
+    [AcaTechnicalSubRating.Four]: 3,
+};
+/** Total order for water: A < B < C < C1 < C2 < C3 < C4 */
+exports.ACA_WATER_ORDER = {
+    [AcaWaterSubRating.A]: 0,
+    [AcaWaterSubRating.B]: 1,
+    [AcaWaterSubRating.C]: 2,
+    [AcaWaterSubRating.C1]: 3,
+    [AcaWaterSubRating.C2]: 4,
+    [AcaWaterSubRating.C3]: 5,
+    [AcaWaterSubRating.C4]: 6,
+};
+exports.ACA_TIME_ORDER = {
+    [AcaTimeSubRating.I]: 0,
+    [AcaTimeSubRating.II]: 1,
+    [AcaTimeSubRating.III]: 2,
+    [AcaTimeSubRating.IV]: 3,
+    [AcaTimeSubRating.V]: 4,
+    [AcaTimeSubRating.VI]: 5,
+};
+/** Lower index = milder risk */
+exports.ACA_RISK_ORDER = {
+    [AcaRiskSubRating.G]: 0,
+    [AcaRiskSubRating.PG]: 1,
+    [AcaRiskSubRating.PG13]: 2,
+    [AcaRiskSubRating.R]: 3,
+    [AcaRiskSubRating.X]: 4,
+    [AcaRiskSubRating.XX]: 5,
+};
+/** @deprecated Use ACA_RISK_ORDER */
+exports.RISK_ORDER = exports.ACA_RISK_ORDER;

package/dist/models/difficulty/difficultyRating.d.ts

@@ -0,0 +1,29 @@
+import type { AcaRiskSubRating } from './acaSubRatings';
+/** Discriminator for page/route difficulty rating scales (extensible). */
+export declare enum DifficultyRatingSystem {
+    ACA = "ACA"
+}
+/**
+ * Registers the parser for {@link DifficultyRating.fromResult} for a given
+ * {@link DifficultyRatingSystem}. Call once per scale from the corresponding module at load time
+ * (see `registerDifficultyRatingParsers.ts`).
+ */
+export declare function registerDifficultyParser(type: DifficultyRatingSystem, parse: (result: unknown) => DifficultyRating): void;
+/**
+ * Base difficulty rating type for page previews and full page views.
+ * Concrete scales extend this (e.g. {@link AcaDifficultyRating}).
+ */
+export declare abstract class DifficultyRating {
+    abstract readonly difficultyRatingSystem: DifficultyRatingSystem;
+    /** Risk level for display (e.g. effective ACA risk). Non-ACA scales may return null. */
+    abstract getEffectiveRiskForDisplay(): AcaRiskSubRating | null;
+    /**
+     * Parses a difficulty rating object from API/JSON. Dispatches on `difficultyRatingSystem`
+     * (or legacy `difficultyType`, case-insensitive); a missing discriminator defaults to
+     * {@link DifficultyRatingSystem.ACA}.
+     */
+    static fromResult(result: unknown): DifficultyRating;
+}
+/** Reads nested difficulty rating JSON from legacy or current property names. */
+export declare function resolveDifficultyRatingFromRecord(r: Record<string, unknown>): unknown;
+//# sourceMappingURL=difficultyRating.d.ts.map

package/dist/models/difficulty/difficultyRating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"difficultyRating.d.ts","sourceRoot":"","sources":["../../../src/models/difficulty/difficultyRating.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,0EAA0E;AAC1E,oBAAY,sBAAsB;IAC9B,GAAG,QAAQ;CACd;AAOD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACpC,IAAI,EAAE,sBAAsB,EAC5B,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,gBAAgB,GAC7C,IAAI,CAEN;AAED;;;GAGG;AACH,8BAAsB,gBAAgB;IAClC,QAAQ,CAAC,QAAQ,CAAC,sBAAsB,EAAE,sBAAsB,CAAC;IAEjE,wFAAwF;IACxF,QAAQ,CAAC,0BAA0B,IAAI,gBAAgB,GAAG,IAAI;IAE9D;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB;CAqCvD;AAED,iFAAiF;AACjF,wBAAgB,iCAAiC,CAC7C,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,OAAO,CAET"}