CLAUDE.md

1# UVEStore — Architecture & Scaling Rules
2 
3## Structure
4 
5The store is built with `@ngrx/signals` and split into feature slices using `signalStoreFeature`.
6 
7```
8store/
9├── dot-uve.store.ts          # Root store — composes all features
10├── models.ts                 # UVEState and top-level types
11└── features/
12    ├── withPageContext.ts     # Shared computed hub (loaded first)
13    ├── editor/
14    │   ├── withEditor.ts     # Editor UI state and methods
15    │   ├── withLock.ts       # Lock management
16    │   ├── save/withSave.ts  # Save operations
17    │   └── toolbar/withUVEToolbar.ts
18    ├── flags/withFlags.ts    # Feature flag signals
19    ├── layout/withLayout.ts  # Layout tab computeds
20    ├── track/withTrack.ts    # Analytics tracking
21    ├── workflow/withWorkflow.ts
22    ├── timeMachine/withTimeMachine.ts
23    ├── client/withClient.ts
24    └── load/withLoad.ts
25```
26 
27## State Design Rules
28 
29### Flat State Structure (Non-Negotiable)
30 
31NgRx Signal Store wraps each root-level property in its own Signal. Nested objects break fine-grained reactivity.
32 
33```typescript
34// ✅ CORRECT: Flat with prefixes
35interface UVEState {
36  uveStatus: UVE_STATUS;
37  pageParams: DotPageAssetParams | null;
38  editorDragItem: EmaDragItem | null;
39  viewZoomLevel: number;
40}
41 
42// ❌ WRONG: Nested objects break reactivity
43interface UVEState {
44  uve: { status: UVE_STATUS };
45  editor: { panels: { palette: boolean } };
46}
47```
48 
49### Domain Prefixes (Required)
50 
51All state properties must use a domain prefix matching their feature file:
52 
53| Prefix | Domain |
54|--------|--------|
55| `uve*` | Global editor system (status, user, enterprise) |
56| `page*` | Page content and metadata |
57| `workflow*` | Workflow and lock state |
58| `editor*` | Editor UI state |
59| `view*` | View modes and preview |
60 
61Cross-domain state (a property with the wrong prefix for its feature) is not allowed.
62 
63### Property Naming Conventions
64 
65| Pattern | Example | Usage |
66|---------|---------|-------|
67| `{domain}{Property}` | `editorDragItem` | State property |
68| `{domain}Can{Action}` | `editorCanEditContent()` | Boolean computed |
69| `${domain}{Computed}` | `$showContentletControls()` | UI-specific computed |
70| `{domain}{Action}` | `viewZoomIn()` | Action method |
71 
72---
73 
74## Key Conventions
75 
76**Computed signals are prefixed with `$`**
77```ts
78$isEditMode: computed(() => pageParams()?.mode === UVE_MODE.EDIT)
79```
80 
81**Each feature exports a `with*()` function** using `signalStoreFeature` with explicit type constraints:
82```ts
83export function withLayout() {
84    return signalStoreFeature(
85        { state: type<UVEState>() },
86        withComputed(...),
87        withMethods(...)
88    );
89}
90```
91 
92**`withPageContext` is the shared computed hub.** It is composed first in the root store, before any other feature. Features that need common computed values (mode, page lock, variant, etc.) declare `props: type<PageContextComputed>()` in their type constraints.
93 
94**State mutations go through `patchState` only.** Never mutate state directly inside `withComputed` or `withMethods`.
95 
96## Rules for Scaling
97 
98### 1. One domain per feature
99Each `with*` function owns one domain (editor UI, layout, workflow, etc.). Do not add state or methods to an existing feature if they belong to a different concern — create a new feature instead.
100 
101### 2. Shared computeds belong in `withPageContext`
102If a computed signal is needed by more than one feature, add it to `withPageContext` and expose it via `PageContextComputed`. Features consume it through `props: type<PageContextComputed>()`. Do not duplicate computed logic across features.
103 
104### 3. Feature-local types live next to the feature
105Each feature keeps its own `models.ts` for state shape, prop types, and enums. Do not import feature-local types into `store/models.ts` — that file is for `UVEState` only.
106 
107### 4. Declare type constraints explicitly
108Always declare `{ state: type<UVEState>(), props: type<PageContextComputed>() }` at the top of `signalStoreFeature`. This enforces that the feature is only composed in the right context and makes dependencies explicit and compiler-checked.
109 
110### 5. Never add logic to the root store
111`dot-uve.store.ts` is a composition file only. It holds `initialState`, wires features together, and adds top-level computeds that genuinely span multiple features (e.g. `$shellProps`). Business logic goes inside the feature, not the root.
112 
113### 6. Sub-features for nested concerns
114Features can nest sub-features (e.g. `withEditor` composes `withUVEToolbar`). Use this when a feature grows large enough that its computeds or methods split into a clearly separate sub-concern. Keep nesting shallow (max 2 levels).
115 
116### 7. `untracked` for side-effect reads
117When a `computed` or method needs to read a signal without creating a reactive dependency, use `untracked()`. Only do this when you have a deliberate reason to break the dependency chain — document why inline.
118 
119### 8. `protectedState: false` is temporary
120The root store has `{ protectedState: false }` to allow state access in unit tests. This must be removed once the tests are updated to use proper store testing patterns. Do not add new tests that rely on direct state mutation.
121 
122---
123 
124## Patterns in Use
125 
126### Accessing State
127 
128Always use computed signals — they are the public API. Never reach into internal raw state.
129 
130```typescript
131// ✅ Use computeds
132const page = store.pageData();
133const canEdit = store.editorCanEditContent();
134 
135// ❌ Do not access internal state signals directly
136const page = store.pageAssetResponse()?.pageAsset.page;
137```
138 
139### `rxMethod` for async operations
140All async flows (`loadPageAsset`, `reloadCurrentPage`, `savePage`, `getWorkflowActions`, `trackUVEModeChange`) are wrapped in `rxMethod`. It binds an RxJS pipeline to the store lifecycle and handles cancellation automatically. Use it for any method that triggers an HTTP call or a side-effect stream.
141 
142```ts
143loadPageAsset: rxMethod<Partial<DotPageAssetParams>>(
144    pipe(
145        tap(() => patchState(store, { status: UVE_STATUS.LOADING })),
146        switchMap((params) => dotPageApiService.get(params).pipe(...))
147    )
148)
149```
150 
151### Optimistic update + rollback via `withTimeMachine`
152`withClient` saves a GraphQL response snapshot before mutating it (`setGraphqlResponseOptimistic`). On save failure, `rollbackGraphqlResponse` restores the previous snapshot using `withTimeMachine`. This is the only place `withTimeMachine` is used — it was designed as a generic undo/redo primitive.
153 
154### Implicit feature composition chain
155`withLoad` internally composes `withClient` and `withWorkflow`. `withSave` internally composes `withLoad`. The root store only calls `withSave`, but it silently gets the full chain. This is intentional but invisible from the root store.
156 
157```
158withSave → withLoad → withClient
159                    → withWorkflow
160```
161 
162### Split `withMethods` blocks for DI ordering
163`withLoad` uses two `withMethods` calls: the first adds `updatePageParams` (no DI needed), the second injects all services. This is a workaround for ngrx/signals requiring methods to be available before they are used inside other methods. Do not collapse them into one block.
164 
165### Feature flag signals as a typed map
166`withFlags` fetches all feature flags from `DotPropertiesService` once and exposes them as a `flags()` signal: a strongly-typed record `UVEFlags`. Consuming features read individual flags via `flags().FEATURE_FLAG_*`. Never inject `DotPropertiesService` inside other features to read flags — always go through `flags()`.
167 
168### Debounced analytics
169`withTrack` wraps tracking calls in `DEBOUNCE_FOR_TRACKING` (5000ms) to avoid noise on rapid state changes. Always apply this wrapper to new tracking methods — raw analytics events on every signal change will flood the analytics backend.
170 
171### `forkJoin` for parallel page bootstrap
172`loadPageAsset` uses two nested `forkJoin` blocks: the first fetches `pageAsset + isEnterprise + currentUser` in parallel, the second (inside the first's `switchMap`) fetches `experiment + languages` in parallel. Each has its own `catchError`. Do not flatten these into sequential calls.
173 
174### `tapResponse` for RxJS next/error handling
175`withWorkflow` uses `tapResponse` instead of `tap` + `catchError` when both the success and error paths need clean inline handling inside a pipeline. Use `tapResponse` when you want to handle both cases close together without breaking the observable chain.
176 
177### `new String('')` for forced iframe refresh
178In `withEditor.$iframeURL`, TRADITIONAL pages return `new String('')` (a String object, not a primitive) instead of a plain `''`. This forces Angular to treat it as a new reference on every recompute, triggering an iframe reload. HEADLESS pages build a full URL with `clientHost`. This distinction is intentional — do not normalize to a plain string.
179 
180### Device and SEO mode are mutually exclusive
181`withView` enforces that device preview and SEO social-media preview cannot be active at the same time. `viewSetDevice()` clears `viewSocialMedia`; `viewSetSEO()` clears `viewDevice`. When adding new preview modes, maintain this mutual exclusion via the same clear-on-set pattern.
182 
183### Type assertion for cross-feature method access
184Features that depend on methods from sibling features (not yet in scope at composition time) use a typed cast: `store as StoreWithDeps<typeof store>`. This is only acceptable for documented circular or out-of-order dependencies. Always define a dedicated `StoreWith*Deps` interface — do not use `as any` except for the documented `withWorkflow` ↔ `withPageApi` circular case.
185 
186---
187 
188## Things to Improve
189 
190### 1. `protectedState: false` (tracked: test infrastructure)
191Root store disables state protection so tests can directly mutate state. Every new test written against this is technical debt. Fix: migrate tests to use `patchState` or store method calls, then remove this flag.
192 
193### 2. Vanity URL redirect inside `withLoad` (tracked: existing TODO in code)
194The `router.navigate()` call in `loadPageAsset` is inside the store. The comment already says it should move to a Shell component effect. Store features should not navigate — they should expose an event or computed that the component reacts to.
195 
196### 3. `isEnterprise` and `currentUser` re-fetched on every page load
197These are session-level facts fetched inside `loadPageAsset`'s `forkJoin`. Every page navigation re-fetches them. The comment in the code references issue #30760 and suggests moving this to an `onInit` lifecycle hook. Until then, every soft navigation pays an unnecessary HTTP round-trip.
198 
199### 4. `$shellProps` computed is too large for the root store
200The root store's `$shellProps` contains the full navigation bar items array with all conditional business logic (enterprise check, layout disabled, rules visibility, experiments). This belongs in a dedicated `withShell` feature, not in the composition root.
201 
202### 5. `saveStyleEditor` does not use `rxMethod`
203Unlike `savePage`, `saveStyleEditor` returns a raw `Observable` that the caller must subscribe to. This breaks the uniform pattern and shifts error handling responsibility to the component. It should be converted to `rxMethod`.
204 
205### 6. Dead reactive dependency in `$editorProps`
206Inside `withEditor`, `$editorProps` calls `store.pageAPIResponse()` at the top of the computed body without using the return value — just to create a reactive dependency. The inline comment says "need more testing before removing this dependency." This is a smell: computed dependencies should be explicit and intentional.
207 
208### 7. `isTraditionalPage` detection is an implicit convention
209`isTraditionalPage` is set as `!pageParams.clientHost` — a boolean derived from the absence of a URL parameter. There is no explicit type guard or enum. If the convention ever changes, this silently breaks every feature that branches on it.
210 
211### 8. `console.error` / `console.warn` scattered across features
212Error handling across `withLoad`, `withSave`, `withWorkflow`, and `withClient` logs directly to the console with no consistent strategy. A store-level error handler or error bus would centralize this.
213 
214### 9. Double `withFlags` composition
215`withFlags(UVE_FEATURE_FLAGS)` is called inside `withPageContext` **and** again in the root store (`dot-uve.store.ts`). The root store call is redundant and confusing — `withPageContext` already includes it.
216 
217### 10. `reloadPageAfterLockChange()` uses raw `.subscribe()`
218Inside `withWorkflow`, the method that re-fetches the page after a lock/unlock uses a manual `.subscribe()` call instead of `rxMethod`. There is no automatic cancellation — if the user navigates away mid-lock, the subscription keeps running. Fix: convert to `rxMethod` or add `takeUntilDestroyed()`.
219 
220### 11. Lock/unlock concern mixed into `withWorkflow`
221`withWorkflow` manages two unrelated things: workflow action fetching (`DotWorkflowsActionsService`) and page lock toggling (`DotContentletLockerService`). The feature's own comments flag this. Lock state and behavior belong in a dedicated feature that focuses only on lock ownership and transitions.
222 
223### 12. `withTimeMachine` is unused
224A generic undo/redo feature exists at `features/timeMachine/withTimeMachine.ts` and is never composed into the store. `withPage` uses `withHistory` instead, which has nearly identical logic. Either delete `withTimeMachine` or replace `withHistory` with it. Having two implementations of the same primitive is maintenance debt.
225 
226### 13. Commented-out permission logic in `withEditor`
227A block of style-editor permission logic in `withEditor` is commented out with no explanation of whether it is WIP or abandoned. It adds noise and creates ambiguity about the intended permission model. Delete it if it is dead code, or activate and document it if it is needed.
228 
229---
230 
231## Next Move
232 
233These are ordered by impact-to-effort ratio:
234 
2351. **Remove the redundant `withFlags` in the root store.** One-line deletion, no behavior change, reduces confusion.
236 
2372. **Convert `saveStyleEditor` to `rxMethod`.** Straightforward refactor. Removes component-side subscription responsibility and aligns with the `savePage` pattern.
238 
2393. **Extract `$shellProps` nav items into a `withShell` feature.** The root store should be a thin composition file. This is the largest source of business logic leaking into the root.
240 
2414. **Move the vanity URL redirect to the Shell component.** Replace the `router.navigate` inside `withLoad` with a dedicated computed or event that the component listens to. This is already documented as a TODO — execute it.
242 
2435. **Fix `protectedState: false`.** Requires updating test setup. High effort but it's the foundation for reliable signal store testing going forward.
244 
2456. **Hoist `isEnterprise` and `currentUser` to `onInit`.** Requires the ngrx/signals lifecycle hook support (issue #30760). When that ships, move these out of `loadPageAsset` to eliminate the per-navigation round-trips.
246 
2477. **Extract lock/unlock to a dedicated `withLock` feature.** The code and its own comments already say this should not live inside `withWorkflow`. Separate the two services (`DotWorkflowsActionsService` vs `DotContentletLockerService`) into their own features for single-responsibility compliance.
248 
2498. **Convert `reloadPageAfterLockChange()` to `rxMethod`.** The raw `.subscribe()` inside `withWorkflow` has no cancellation. It should use `rxMethod` like every other async operation in the store.
250 
2519. **Delete `withTimeMachine` or replace `withHistory` with it.** Two nearly identical undo/redo implementations exist. Pick one and remove the other. `withTimeMachine` has better JSDoc but is unused; `withHistory` is actively composed. Consolidate before the divergence grows.
252