iptvnator/docs/architecture/parental-lock.md

# Parental Lock

Issue #285. A PIN-protected lock for individual categories: Xtream
categories, Stalker genres and M3U `group-title`s. While the lock is active,
everything in a locked category is withheld from the app; entering the PIN
shows it again until the app locks itself.

This document is the contract. Phase 1 (this document's scope) covers the
portals' own surfaces; the aggregate surfaces listed under "Not yet covered"
follow in a second PR.

## Product rules

- Off by default. Enabling asks for a new PIN (4–8 digits); disabling and
  changing the PIN always verify the current PIN against the stored hash,
  even while the session is unlocked (`verifyCurrentPin()`, never the
  `requestUnlock()` short-cut) — a parent leaving the app unlocked must not
  leave the lock removable. Disabling keeps the locks for a later re-enable.
- The unit of locking is the category. Nothing is blurred or greyed: a
  withheld category and its rows are absent. The only trace is one
  "N locked · Enter PIN to show" row at the bottom of a portal's category
  rail, which opens the PIN prompt. In fail-closed mode (lock store
  unreadable) the row shows without a count, since which categories are
  locked is unknown while every one of them is withheld.
- The unlock lives in memory only. The app locks again on every restart, on
  "Lock now" (header button, command palette, settings), and after
  `Settings.parentalLockRelockMinutes` minutes without user interaction
  (default 15; `0` = only on restart). The idle timer follows the UNLOCKED
  transition: armed the moment a session is unlocked — including the session
  that just enabled the feature — and disarmed on lock. Active playback of a built-in web
  player counts as interaction, so a film never locks half way — video
  through the keep-awake tracker, and audio (the radio player) read from
  the playing `<audio>` elements, since the keep-awake service ignores
  them.
- This is a child lock, not a security boundary: the PIN hash and the lock
  store sit in user-readable app data. The UI says so. There is no PIN
  recovery; resetting the app data is the way out.

## Storage

| What               | Where (Electron)                                                                  | Where (PWA)               |
| ------------------ | --------------------------------------------------------------------------------- | ------------------------- |
| PIN hash           | `app_state` key `parental-lock:pin`                                               | localStorage, same key    |
| Lock store         | `app_state` key `parental-lock:locks`                                             | localStorage, same key    |
| Feature switch     | `Settings.parentalLockEnabled`, mirrored to electron-conf `PARENTAL_LOCK_ENABLED` | `Settings`                |
| Relock timeout     | `Settings.parentalLockRelockMinutes`                                              | same                      |
| Xtream query index | `categories.locked` column                                                        | none (filtered in memory) |

The PIN is hashed with PBKDF2-SHA256 through WebCrypto
(`parental-lock-pin.util.ts`, format `v1$<iterations>$<salt>$<hash>`), so
Electron and PWA share one implementation. The hash is deliberately not part
of `Settings`: settings are logged, backed up and mirrored to the main
process. A hash that could not be READ is not an absent PIN:
`ParentalLockStorageService.readPinHash()` reports the failure as `null`
(an absent PIN is `{hash: null}`), the session then stays locked (`enabled`
treats an unreadable PIN as set while the switch is unknown) and every
PIN-protected step — unlock, change PIN, disable — re-reads it first, so
storage answering later is enough to recover without a restart.

The lock store (`ParentalLockStore` in `parental-lock.util.ts`) is keyed by
playlist id and holds, per playlist, Xtream `{categoryType, xtreamId}`
pairs, Stalker `{categoryType, categoryId}` pairs and M3U group titles. It
is the source of truth for all three portal types. Xtream additionally keeps
`categories.locked` as a SQLite index derived from it: `DB_SET_CATEGORY_LOCKS`
re-stamps one playlist/type from a provider-id list (idempotent, so the store
can be replayed after a refresh or a backup restore), and `DB_SAVE_CATEGORIES`
takes `lockedCategoryXtreamIds` so a refresh recreates the rows already
stamped. Locks are keyed by provider ids, never by SQLite row ids, because a
refresh deletes and re-inserts the rows.

## Enforcement — two layers, both default-closed

1. **SQLite worker (Electron).** `apps/electron-backend/src/app/database/parental-lock-state.ts`
   holds one process-wide flag. While active, every content-returning read
   appends "category is not locked": `getCategories`, `getContent`,
   `searchContent`, the three `globalSearch` candidate selectors,
   `getGlobalRecentlyAddedByType`, `DB_MATCH_TITLES` and the multi-source
   discovery queries. A surface added later is therefore withheld by
   default. The flag is seeded through `workerData.parentalLockActive` when
   the worker is (re)started and flipped by the `parental-lock` control
   message on the request port (ordered with the requests, so a read posted
   after it observes the new state). `getAllCategories` is exempt: it feeds
   the management dialog, which itself sits behind the PIN.
2. **Renderer `ParentalLockService`** (`libs/services/src/lib/parental-lock/`).
   Signals `enabled`, `unlocked`, `active` (= enabled && !unlocked),
   `hasPin`, `version`; `requestUnlock()` (one shared prompt for concurrent
   callers), `lock()`, `setupPin()`, `changePin()`, `disable()`, the lock
   store API (`setXtreamLocks`, `setStalkerLocks`, `setM3uLocks`,
   `replacePlaylistLocks`, `lockedXtreamIds`, …) and the `is*Locked`
   predicates, which answer `true` only while `active`. The PIN dialog is
   reached through the `PARENTAL_LOCK_PROMPT` token, provided by the app
   (`AppParentalLockPromptService` → `ParentalLockPinDialogComponent` in
   `libs/ui/components`), so the data-access lib stays free of UI.
   Five wrong PINs pause the prompt for 30 seconds. The count and the
   pause live in the service (`createParentalLockPinThrottle`, handed to
   every unlock prompt), so dismissing the dialog and opening it again
   does not reset them.

The renderer reports `active` to the main process over
`PARENTAL_LOCK_SET_STATE` (`apps/electron-backend/src/app/events/parental-lock.events.ts`),
which forwards it to the worker. `SETTINGS_UPDATE` only persists the
`parentalLockEnabled` mirror; it never derives the live state from a settings
save (every save carries the flag unchanged and would re-lock the worker
under a renderer that shows "unlocked"). The one exception is a switch-off,
which releases the worker at once. `requestUnlock()` awaits `initialize()`
before it can answer "not active", so a slow settings load cannot open a
gate. Like the playback keep-awake vote, the
renderer's word does not outlive its page: on reload, main-frame navigation or
a dead render process the flag falls back to the mirrored
`PARENTAL_LOCK_ENABLED` setting, i.e. locked while the feature is on. The
renderer, in turn, reports nothing before its settings have loaded, so it can
never send a spurious "unlocked" while the main process still holds the
locked default. Unreadable settings fail the same way: `SettingsStore`
serves defaults and records `storageFailure = 'load'`, and the switch is
then unknown rather than off — a stored PIN stands in for it (`enabled`
follows `hasPin`, so the session starts locked and one PIN entry unlocks
it), and without a PIN the renderer does not report at all, leaving the
main process on its mirrored default instead of announcing "unlocked" on
the strength of default settings. The lock store itself fails closed the
same way: `ParentalLockStorageService.readLocks()` reports a failed read as
`null` (distinct from an absent store, `{}`; Electron reads through
`DatabaseService.readAppState`, which keeps a rejected IPC apart from a
missing key, and a stored payload that does not parse or does not have the
shape `writeLocks` produces — `isWellFormedParentalLockStore`, all three
lists present, down to the nested entries — is a failed read too — corruption never becomes an empty
store), and while the lock is active with the store unreadable
`ParentalLockService.withholdsEverything` is true — every `is*Locked`
predicate answers true and the set-based filters (PWA Xtream, Stalker
content and search, the M3U channel list) receive
`ALL_CATEGORIES_WITHHELD`, and `ElectronXtreamDataSource` serves no
categories, content, cached categories/content (the warm-route hydration
path) or search hits either, since its SQLite index may still
carry a stale stamp — under which a row WITHOUT a genre is withheld
too (`isStalkerItemWithheld`, `isStalkerCategoryLocked`), since "no genre"
must not be the one row a withheld catalog still shows — so the whole
catalog is withheld until the PIN
is entered or the store reads again (`requestUnlock` and every lock write
retry the read first, and a write is refused while it still fails, since it
would be built on an empty in-memory store and wipe the persisted locks).
The same fail-closed mode applies while locked when Electron reads Xtream
through the SQLite worker (`supportsXtreamSqliteDataSource`) but the bridge
lacks the worker filter (`supportsParentalLockSqliteFilter`:
`setParentalLockState` and `dbSetCategoryLocks`, e.g. a partial or older
preload): the worker would never learn the lock state, so it cannot
withhold locked rows itself. The same holds while locked after the
lock-state sync itself was rejected (`ParentalLockWorkerSync`), until a
later sync succeeds. The direct worker consumers
(`CatalogTitleMatchService`, `VodSourceDiscoveryService`) ask the worker
nothing while `withholdsEverything` is true, in either case. The VOD
multi-source host keys its discovery session to the lock version: a lock
change drops the discovered sources, retires discoveries and switches in
flight, and rediscovers through the worker's new lock state. Title-match
results are cached by their consumers (Xtream/Stalker Actor and Discover
routes, the dashboard trending and recommendation rails, the four
"similar in your portals" rails), so each filters them on READ through
`CatalogTitleMatchService.visibleMatches` / `isWithheld` or
`CrossPortalSimilarService.visible`. Every match carries its provider
category id, and the predicate reads the lock state, so a relock hides
matches cached while unlocked (and those of a lookup issued before it) at
once, with no re-query; an unlock shows them again. Consumers keep ALL the
rows a lookup returned and pick a title's match from the visible ones on
read (the Actor/Discover indexes, the trending rail, the recommendation
rail through `buildRecommendationItems`, and each "similar" item's
`candidates`), so a title that also exists in an unlocked portal stays
available through that copy instead of disappearing with the locked one.
The window before the initial read settles is treated the same way
(`ParentalLockLockStore.readable` is false until then): settings can report
the feature as on before the locks are known — and the workspace route's
`settingsReady` resolver awaits `ParentalLockService.initialize()` next to
the settings load, so no route or catalog activates before the PIN and the
lock store are known (in the PWA the settings read can be the slower one).
Every lock write re-reads a failed store BEFORE building its edit, so a
recovered store is edited, never overwritten by an edit built on the empty
fail-closed one. The feature switch itself is
persisted through one guarded path (`persistEnabled`), and every
parental-lock settings write first retries a failed startup settings read
(`ensureSettingsReadable`) and is refused while settings stay unreadable —
`updateSettings` writes the whole settings object, which after a failed
read is the defaults and would replace the user's persisted preferences.
Within that path `updateSettings`
patches memory before it writes, so a failed write is undone in memory and
`setupPin`/`disable` report false (whether to persist is decided from the
settings switch BEFORE the PIN is stored, since `enabled` follows `hasPin`
while the switch is unknown); the Electron mirror write is awaited
next, and a mirror that cannot be written undoes the settings write the
same way — the toggle never shows a state the next launch will not have,
on either side. The undo restores the value read AFTER the settings retry
(not the hard-coded inverse, which a recovered read may already hold). The
Settings switch itself only requests the change: it snaps back to the
saved state at once and follows `enabled()` when the PIN action succeeds,
so a cancelled or refused PIN leaves it showing the real state.

### In-memory catalogs

- **Xtream (Electron):** the store reads categories and streams through the
  worker, so they arrive filtered. On `version` changes
  `ParentalLockEnforcementService` (`apps/web/src/app/services/`) calls
  `XtreamStore.reloadCategories()` + `reloadCachedContent()` and, if the
  selected category vanished, clears the selection and navigates to the
  section root. The selected ITEM is judged separately, on its own
  `category_id` against the reloaded category list: a detail opened from
  "All", recently added or search has no selected category to vanish
  with, so its row disappearing from a list is not enough — the item is
  cleared and the route returns to the section root while the (still
  readable) selected category stays. Within one apply the synchronous
  surfaces (the M3U active channel, the Stalker selection) are stepped off
  BEFORE the Xtream reloads are awaited, so a playing M3U channel never
  waits behind a slow portal read — the Xtream store stays populated after
  leaving that portal, so its reload runs on every apply. The M3U check
  also runs whenever the active channel changes while locked: numeric
  zapping, next/previous and remote commands select from the full channel
  list without any lock change following, so a channel of a locked group
  is reset as soon as it becomes active (numeric zapping also skips it). Applies run one
  at a time and each is
  abandoned once a newer `version` exists (the queued apply reads the latest
  state): `ElectronXtreamDataSource` shares in-flight category/content
  reads per playlist and type, and its share key carries the lock version,
  so an unlock refresh still running when "Lock now" arrives can never hand
  the relock its unfiltered rows. The apply also re-runs the stored
  in-portal search (`XtreamStore.refreshSearchResults`, the last
  `searchContent` call as issued) — `searchResults` is a separate array the
  search page renders directly and would otherwise keep locked titles until
  the query changes. A RELOCK fails closed at once rather than after the
  database answers — ahead of the serialized apply queue, so an earlier
  apply still waiting on a slow or hung read cannot delay it: the selected detail is stepped off synchronously when
  the lock store already names its category (the pre-reload category list
  maps Electron's row id to the provider id) or when that list cannot place
  it at all (a manually hidden category opened through search), then
  `withholdCatalog()`
  empties every catalog list and `clearSearchResults()` the stored search
  (retiring a search still in flight, which was issued under the previous
  lock state) before the filtered reads refill them; both reloads take a publish guard
  answered before every state patch, so a read issued under an older lock
  version is dropped instead of published. The guard also turns false once
  another Xtream playlist is open (the store is a singleton), and the store
  itself refuses to publish a reload into a playlist it was not read for;
  the post-reload search refresh and selection checks are skipped then
  too. The post-reload checks of the
  selected category and item decide by the LOCK STORE through the
  unfiltered category rows (`IXtreamDataSource.getAllCategories`), not by
  absence from the reloaded list, which also omits categories the user
  merely hid; rows that cannot be read fail closed. A lock change that overtakes
  the INITIAL hydration (the content is not initialized yet, so the reload
  has nothing to re-read) sets a deferred-reload flag instead — already
  when `withholdCatalog()` empties the lists, before the category reload is
  awaited: the
  hydration then publishes empty lists in place of the rows it read under
  the previous lock state (categories included), and the filtered reload
  of categories and content runs as soon as the hydration settles, on
  every path that marks the content initialized, under the publish guard
  of the request that deferred it.
  Both reloads fail closed: a category reload that
  rejects empties the three category lists, and a per-type content reload
  that rejects empties that type and sets it back to `idle` so the next
  visit loads it again (filtered) — rows read under the previous lock state
  are never kept. Live playback is stopped by the layout itself:
  `LiveStreamLayoutComponent` keeps the playing channel's provider category
  id (mapped from the SQLite row id on Electron — through the visible
  category list, else through the unfiltered rows, since search can play a
  channel of a HIDDEN category; until that lookup lands the id is unknown
  and a relock stops the channel, and a lookup that lands after a later
  playback — same provider id, other playlist — is discarded) and drops `activePlayback` on a `version`
  change that locks it, because the player is gated on that
  signal, not on the store selection — which an ordinary category switch
  also clears while the channel keeps playing.
- **Stalker:** the same service checks the selected genre through
  `isStalkerCategoryLocked` and, independently, the selected item's own
  genre — `tv_genre_id` for live and radio rows, `category_id` for VOD and
  series, the rule the store's withheld filter applies — so an item opened
  from `*` (All) or search is withheld by its genre even though `*` itself
  can never be locked. A withheld item is cleared and the section root is
  navigated to; the category selection is reset only when the genre itself
  is locked. A stream still RESOLVING at relock time is retired too: the
  embedded player defers selecting the channel until resolution, so the
  cleared selection cannot retire it — the playback request carries the
  lock version it was issued under (`isStalkerPlaybackRequestLockCurrent`)
  and is dropped when the session relocked meanwhile (an unlock lets it
  complete). `StalkerLiveStreamLayoutComponent` drops its `activePlayback`
  whenever the store selection is cleared: its template mounts the player
  only with a selection, and the held stream must not resurface with the
  next one.
- **M3U groups rail:** `ChannelListContainerComponent` derives
  `withheldGroupCount` (groups of the playlist the active lock withholds)
  and the groups rail renders the same "N locked · Enter PIN to show" row
  as the portal category rail, so locked groups do not simply vanish —
  also when EVERY group is locked: the container keeps the groups view
  (`showChannelViews`) and the groups view keeps its rail instead of the
  generic empty state.
- **Xtream (PWA):** `PwaXtreamDataSource` drops withheld categories,
  streams and search hits at read time; the same reloads apply. Provider
  category ids are compared in canonical numeric form (`"009"` matches the
  stored lock `9`), as the lock editor stores them with `Number`.
- **Warm-cache detection (Electron):** the filtered category/content reads
  can be empty while the offline cache is complete (every category locked),
  so `ElectronXtreamDataSource` confirms an empty read with the unfiltered
  `hasXtreamCategories` / `hasXtreamContent` before refetching from the
  provider.
- **Routes:** `parentalLockXtreamCategoryGuard(section)` on every Xtream
  `:categoryId` route (live, vod, series and their detail children) and
  `parentalLockStalkerCategoryGuard(section)` on the Stalker vod/series
  `:categoryId` routes prompt for the PIN when a locked category is reached
  by URL — bookmark, typed address, stale link — and redirect to the section
  root on refusal. Detail routes also resolve the ITEM's own category through
  `getContentByXtreamId`, so a locked movie paired with an unlocked category
  id in the URL is still refused; on a cold PWA navigation the guard
  hydrates the session cache first (`getPlaylist` + `getContent`), and an
  item the catalog cannot place fails closed (PIN prompt) rather than
  passing as unlocked. Electron routes carry SQLite row ids, so
  the Xtream guard maps them through the unfiltered category read; Stalker
  routes already carry the genre id.
- **Stalker withheld-row bookkeeping:** the paging logic that advances past
  a page made only of withheld rows keys those rows by
  `stalkerWithheldRowKey` (`id`, else `stream_id`/`movie_id`/`series_id`,
  else the row's `cmd`/`name`), never by a shared `''`, so a page of new
  locked rows is not mistaken for a stalled portal.
- **Stalker search relock:** a lock change drops the withheld rows already
  on screen at once (`applyRelockToResults`, page 1 included) and closes an
  open detail of a now-withheld genre (in fail-closed mode also one
  without a genre), before the replacement page is awaited — otherwise
  they stay clickable while that request is pending.
- **Stalker search staleness:** portal requests are not aborted, so a
  search page issued before a relock can finish after it, filtered with the
  pre-relock withheld set; `isStalkerSearchRequestCurrent` keys the
  response on the parental lock version as well as term/type/page/portal,
  so such a page is dropped instead of repopulating the grid.
- **Stalker search route** (`/workspace/stalker/:id/search`, no category
  in the URL): `StalkerSearchComponent` filters each portal page through the
  same withheld-genre predicate, carries `parentalLockVersion` in its
  resource params, judges paging progress on the raw page (a page made only
  of locked rows is not the end of the results), advances past a run of
  fully withheld pages by itself (the infinite scroll stops auto-filling
  after a few no-growth loads), closes an open detail whose genre is newly
  withheld and, on a lock flip past page 1, drops the withheld rows and
  restarts from page 1.
- **Stalker:** genres are stored unfiltered; `getCategoryResource` filters
  them, `getAllCategoriesForSelectedType` is the raw list for the lock
  dialog. `itvFullChannelList` and the content loader drop rows whose
  `tv_genre_id` / `category_id` is withheld, the content resource's params
  carry `parentalLockVersion` so lock/unlock re-fires it, and a stale
  response is discarded when the version moved. Paging is judged on the RAW
  page: withheld ids the list has not seen before count as progress (so a
  portal page made only of locked rows does not end the list), a page that
  is entirely withheld requests the next page by itself, and the VOD/series
  `totalCount` is reduced by the withheld ids seen so the grid stops asking
  once every visible row is in. A lock flip while the list sits past page 1
  drops the withheld rows on screen at once and restarts from page 1, so rows
  accumulated under the old lock state are never appended to. A selected
  withheld genre is cleared and the
  section root is navigated to.
- **M3U:** `ChannelListContainerComponent` derives one `visibleChannelList`
  (all views, favorites, recents, the fullscreen panel and numeric zapping
  read from it); locked groups are absent from the groups rail. A playing
  channel of a locked group is reset on lock.

## UI

- `Settings → Parental lock` (`/workspace/settings/parental`): enable
  toggle, state + Lock now / Unlock, relock select, Change PIN, the
  disclaimer. Everything applies immediately (it gates on the PIN), outside
  the shared dirty form; `createSettingsFromFormValue` carries both values
  from the current settings so Save cannot undo them.
- One entry point per rail, the same on every portal type: the "Manage
  categories" button (`tune` icon; "Manage groups" on an M3U playlist).
  Xtream and M3U render lock toggles inside their existing hide/show
  dialogs while the feature is on; Stalker has no hide/show dialog, so its
  button — shown only while the feature is on — opens the lock-only
  `StalkerCategoryLockDialogComponent`, which also offers "Lock adult
  (18+)" for genres the portal flags `censored`. All three list the locked
  names and can rewrite the locks, so each opens only after
  `requestUnlock()` succeeds — and closes itself, discarding the draft, the
  moment `active` becomes true again (idle relock, Lock now), since the
  PIN gate covers only the opening. The M3U group dialog does this only
  while it carries lock toggles; the plain hide/show editor is not behind
  the PIN. The Xtream dialog loads its candidates through the
  capability-selected data source (`IXtreamDataSource.getAllCategories`,
  which the PWA source answers from its session cache or the API), so PWA
  users can set locks too; the hide/show checkboxes, the selection count
  and the Select/Deselect-all actions remain Electron-only.
  A deliberate non-choice: no dedicated lock button in the rail header
  (the header already carries search, sort and manage, and the lock is a
  category-management concern) and no keyword-based "adult" recognition
  for Xtream/M3U (provider naming is arbitrary; the only automation is the
  portal's own `censored` flag on Stalker).
- Right-click accelerator: a `contextmenu` on a category row (Xtream and
  Stalker rail, `WorkspaceContextCategoryViewComponent`) or an M3U group
  row opens the shared `CategoryLockMenuComponent` (`libs/ui/components`)
  with one "Lock / Unlock category (group)" item, only while the feature
  is on. The portal rail persists through
  `WorkspaceCategoryLockActionService` (PIN gate, then one-id edit of the
  lock store, failure snackbar); the M3U rail emits the toggled group to
  `ChannelListContainerComponent`, which captures the playlist, asks for
  the PIN, and persists the edit only if that playlist is still open (two
  playlists can share a group name). The M3U management dialog is bound
  the same way: `GroupsViewComponent` captures its `playlistId` input
  before the PIN and drops the dialog's result once another playlist is
  open. Every bulk lock editor (Xtream and M3U management dialogs, the
  Stalker lock dialog) builds its draft only from a lock store that was
  read (`ensureLocksReadable`): a draft taken from the empty fail-closed
  snapshot would erase the real locks on Save if storage recovered in
  between. The M3U and Xtream dialogs then open without lock toggles; the
  Stalker dialog does not open. Every one of them closes on a relock, the
  M3U one also when it opened without toggles, since it still lists every
  group name. Bulk actions stay in the dialog, and while the session is locked
  a locked category is not in the rail, so unlocking always goes through
  the "N locked · Enter PIN to show" row or the dialog. The M3U dialog
  hands its lock list back to `ChannelListContainerComponent`, which
  awaits the write and reports a failed save in a snackbar (the dialog has
  closed by then). On Electron the `categories.locked` re-stamp
  (`setCategoryLocks`) clears and re-locks one playlist/type inside ONE
  transaction, so a failed restamp keeps the previous index instead of
  leaving every category unlocked. The relock timeout persists through the
  same undo-on-failure pattern as the switch (`setRelockMinutes` reverts
  the in-memory value and the facade shows the settings save-failure
  snackbar). A locked session cannot change it: the selector is disabled
  until the PIN is entered, and `setRelockMinutes` refuses while `active`,
  so a child cannot switch the idle relock off for the next unlock.
- Header lock/unlock button and the `parental-lock-now` /
  `parental-unlock` palette commands.
- The PIN dialog's submit button names the flow: the service passes a
  `submitKey` with every prompt — Unlock (`requestUnlock`), Save PIN (a new
  PIN in `setupPin` and `changePin`), Confirm (the current PIN before a
  change), Turn off (`disable`). The dismiss button is the shared Cancel.
  Errors sit on their field as `mat-error` (an `errorStateMatcher` drives
  it, so the input gets `aria-invalid` and the message lands in the field's
  live region): a wrong PIN, the cooldown or a too-short PIN on the PIN
  field; a mismatch on the repeat field, shown while typing once the repeat
  is as long as the PIN. Submit is disabled only while busy or cooling
  down, never for incomplete input, because Enter does nothing on a
  disabled default button; `submit()` refuses instead, shakes the field
  (no shake under `prefers-reduced-motion: reduce`) and focuses it — except
  that Enter in the PIN field with the repeat still empty only moves focus
  to the repeat (a `keydown.enter` handler: focus cannot tell Enter from a
  click on Save, since WebKit does not focus a clicked button). Set
  mode marks both inputs `autocomplete="new-password"`. The Electron
  `parental-lock-pin-dialog.e2e.ts` covers the labels and the
  mismatch → fix → save flow.
- Styling uses app tokens only (the theme declares no `--mat-sys-*`); the
  PIN errors, the fields' error outline and the Stalker adult chip use a
  local red per theme. Keyboard
  focus on a lock row is a 2px inset `--app-selection-color` ring, and the
  lock dialogs open with `maxWidth: 'calc(100vw - 32px)'` and no content
  min-width, so they fit a 375px phone. `apps/web-e2e/src/parental-lock-ui.e2e.ts`
  checks rings, borders, the PIN error and phone width in both themes.

## Startup footprint

The lock service, lock store and enforcement are on the renderer's initial
path by necessity (the workspace resolver and the catalog data sources gate
on them). Everything else stays lazy: the PIN dialog loads through
`parental-lock-pin-dialog.lazy.ts` on the first prompt (a failed chunk load
reads as a cancelled prompt), and the enforcement's Stalker step loads
through `parental-lock-stalker-enforcement.ts` only while a Stalker route is
open — a static import of the Stalker store would put the whole Stalker
data layer back into `main.js`. The chunk is preloaded when a Stalker route
opens, so a relock there runs the step synchronously; if it is not loaded
yet (still fetching, or it cannot load — a stale PWA page after a
deployment) the step fails closed at once by navigating to
`/workspace/sources`: leaving the Stalker route clears its selection and
stops its playback, and the Xtream step still runs. The feature costs about 35 KB of
`renderer.initialBytes`; the baseline was not raised for it, the growth was
offset by moving lazy-only barrel re-exports (backup/restore and the portal
helpers) off the initial path.

## Lock store lifetime

On Electron the SQLite `categories.locked` index is derived from the lock
store and must never lag behind it, because the worker filters every read
by the index alone:

- The store commits BEFORE the re-stamp, so a failed re-stamp rolls the
  store back to the previous locks AND re-stamps every touched type from
  them (a backup restore stamps three types, and the ones before the
  failing type already carry the new locks). The store revision consumers
  reload on is published only once every touched type is stamped — also
  after a rollback — so a reload cannot read a later type through its old
  stamps. If the rollback write or its re-stamp fails too, the playlist is
  marked stale and re-stamped on the next store access. A failed rollback
  WRITE still puts memory back to the previous locks and leaves a pending
  rewrite: the next store access persists them before it re-stamps, so the
  failed edit cannot take effect through that re-stamp. The pending rewrite
  lives in memory: if the app exits before it lands, the next launch loads
  the persisted copy, i.e. the edit the parent submitted with the PIN. That
  is accepted — it is not a bypass, and a durable rollback journal would
  hit the same storage failure. For the whole
  re-stamp window — store changed, stamps not yet landed — the playlist
  counts as stale, so `readable` is false and a relock inside the window
  reloads fail-closed instead of through the old stamps. Such in-flight
  entries are not retried by a reconcile running beside the write (a PIN
  prompt or backup calling `ensureReadable()`): it would stamp from a store
  the write has not committed yet. Only failed stamps are retryable.
- A write that removes a playlist's LAST lock clears the index first and
  drops the key afterwards: the launch-time reconcile finds playlists only
  through their key, so an interruption must leave store-with-lock and
  index-without, which the next reconcile repairs toward locked. If the
  clear or the store write fails, the index is re-stamped from the previous
  locks at once — title matching and multi-source discovery query the
  worker directly and trust the index, so a stale flag alone would not
  protect them. The playlist stays stale until the store write has landed
  too: while it is pending the index is already cleared but the store
  still holds the lock.
- An edit that takes a lock away commits only while the session is
  unlocked, checked inside the write queue at commit time
  (`ParentalLockLockStore.setRemovalGate`, set by `ParentalLockService`).
  An editor opened while unlocked may still be saving, or queued behind
  another write, when the app relocks. The gate is asked right before the
  edit's first write is issued; a relock that lands after that is ordered
  after the write, which completes: the parent authorized that removal,
  and a post-write rollback could itself fail and leave the persisted
  store diverged from memory across a restart. (During the Xtream stamps
  the playlist is stale anyway, so the relock reloads fail-closed until
  they land.) Adding locks is always allowed.
  Playlist deletion and "Remove all playlists" are not edits and are not
  gated.
- Every launch re-derives the index from the store for each playlist that
  has locks, and a store recovered by a later successful read marks its
  playlists stale the same way. The reconcile is awaited inside the store's
  `load()`, so `readable` (and with it every catalog read the renderer
  gates) stays false until the index agrees with the store; a re-stamp that
  keeps failing keeps the session fail-closed.

Every lock-store mutation runs through one write queue in
`ParentalLockLockStore`: each rewrites the whole persisted store from the
in-memory copy, so overlapping edits (two right-click toggles, a dialog
save during a restore) would otherwise snapshot the same store and the
later write would drop the earlier edit. Single-row changes (the
right-click Lock/Unlock) are passed as an EDIT of the current list
(`LockListEdit`), evaluated inside that queue, so two quick toggles each
see the other's result instead of one shared snapshot; the dialogs pass a
full list, which is the replacement they mean. A deleted playlist's locks leave
the store through the `PLAYLIST_DELETE_CLEANUP` hook
(`provideParentalLockPlaylistCleanup`, run by
`PlaylistsService.deletePlaylist` for every single-playlist deletion; no
re-stamp, the category rows go with the playlist), and "Remove all
playlists" empties it through `ParentalLockService.clearAllLocks` once the
deletion has succeeded — the in-memory store empties at once, and a failed
persisted clear is retried on the next store access (the store is not
`readable` until it lands). A backup restore that CREATES a playlist (not a merge) starts
that playlist from empty locks, so a reused id can never inherit entries a
failed cleanup left behind; the restore retries a failed lock-store read
first (`ensureLocksReadable`) and aborts while it still fails, so that check
never runs against the empty fail-closed snapshot.

## Backup

A backup carrying lock lists replaces the matching playlists' locks,
possibly with an emptier set, so the import asks for the PIN first (after
the file was chosen) and aborts when it is refused. That answer can go
stale during a long import (idle relock, "Lock now"), so an entry whose
restore would take a lock away asks again right before it replaces locks
if the app has relocked; a refusal fails that entry and keeps its previous
locks. A restore that only adds locks is not asked again. Locks are
restored LAST
for each entry, after the Xtream data restore, so a
failed merge leaves the playlist's previous locks in place. M3U group titles
travel verbatim (`normalizeParentalLockGroupTitles`, exact
dedup): locks match `channel.group.title` exactly, so the trimming
`uniqueStrings` used for favorites would weaken a lock on a title with
surrounding whitespace. A backup's lock lists are validated entry by entry
on import (`isWellFormedParentalLock*` in the shared contract): restore
treats them as authoritative and the normalizer drops what it does not
understand, so a damaged list is rejected rather than erasing the
playlist's persisted protection.

`lockedGroupTitles` (M3U), `lockedCategories` (Xtream `{categoryType,
xtreamId}`, Stalker `{categoryType, categoryId}`) travel in each entry's
`userState`, written only when the playlist has locks. Absent means "no
opinion" and restore leaves the target's locks alone; present replaces them
(`replacePlaylistLocks`, which also re-stamps the Xtream index). The PIN is
never exported.

## Not yet covered (phase 2)

Favorites, recently viewed, playback positions / Continue Watching, the
dashboard rails built from Stalker and M3U documents, global favorites /
recent pages, the EPG guide, downloads and recordings lists, the remote
control's channel-number resolvers, the command palette's channel search and
the Electron-only global search page (`/workspace/search`, whose stored
results are not re-run on a relock) still show rows from locked categories. The SQLite-side hooks exist
(`unlockedCategoryCondition()` / `unlockedCategorySql()`), the renderer
predicate is `ParentalLockService.is*Locked`.

## Files

- Contracts: `libs/shared/interfaces/src/lib/parental-lock.util.ts`,
  `parental-lock-pin.util.ts`, `Settings.parentalLock*`,
  `PARENTAL_LOCK_SET_STATE`.
- Renderer: `libs/services/src/lib/parental-lock/` (`ParentalLockService`
  owns the session state and PIN flows; `ParentalLockLockStore` owns the
  persisted lock set, its unreadable state and the SQLite re-stamp),
  `apps/web/src/app/services/parental-lock-prompt.service.ts`,
  `parental-lock-enforcement.service.ts`,
  `apps/web/src/app/settings/settings-parental-section.component.*` and `settings-parental-lock.facade.ts` (rows anchored and indexed for settings search),
  `libs/ui/components/src/lib/parental-lock-pin-dialog/`,
  `libs/portal/stalker/feature/src/lib/stalker-category-lock-dialog/`.
- Electron: `apps/electron-backend/src/app/database/parental-lock-state.ts`,
  `services/parental-lock-state.ts`, `events/parental-lock.events.ts`,
  `database/operations/category.operations.ts` (`setCategoryLocks`).