docs: fix bootstrap — remove JWT Bearer claim; add mistakes 16-17; add pres_mgmt reading entry

- Auth row in stack table wrongly said "JWT Bearer is auto-injected" — this project
  uses custom headers only (x-aether-api-key + x-account-id, NOT Bearer tokens)
- Mistake #16: $ sigil on plain prop value → store_invalid_shape at runtime
- Mistake #17: *_json / *_kv_json columns start as null — require ?. and ?? {} guards
- Renumbered old #16 (service worker) to #18
- Reading order: added Pres Mgmt module doc pointer

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
2026-06-12 16:19:52 -04:00
parent 94bdeb9a26
commit 10f7f04fbc

View File

@@ -29,7 +29,7 @@ running in Docker. The frontend talks to it exclusively via the V3 REST API.
| Editors | CodeMirror 6 (primary), Edra/TipTap (secondary) | | Editors | CodeMirror 6 (primary), Edra/TipTap (secondary) |
| Native | Electron app for onsite launcher (`src/lib/electron/electron_relay.ts`) | | Native | Electron app for onsite launcher (`src/lib/electron/electron_relay.ts`) |
| Backend | FastAPI + MariaDB, V3 API (`/v3/crud/`, `/v3/lookup/`) | | Backend | FastAPI + MariaDB, V3 API (`/v3/crud/`, `/v3/lookup/`) |
| Auth | Custom headers: `x-aether-api-key` + `x-account-id`; JWT Bearer is auto-injected when a session exists | | Auth | Custom headers only: `x-aether-api-key` + `x-account-id`**NOT** Bearer tokens |
--- ---
@@ -474,7 +474,39 @@ These are real incidents — know them before you start.
**Exception — legacy `ae_events__event.ts` encoding:** `ae_events__event.ts` (and `ae_events__event_session.ts`) do NOT use `build_tmp_sort`. They use `priority ? 1 : 0` (priority=true→`'1'`), which requires **descending** sort to put priority items first. `ae_events__event_presentation.ts` DOES use `build_tmp_sort` (it overrides the generic encoding in its `specific_processor`). Do not apply the ascending rule to raw event or session sorts until those modules are migrated to `build_tmp_sort`. **Exception — legacy `ae_events__event.ts` encoding:** `ae_events__event.ts` (and `ae_events__event_session.ts`) do NOT use `build_tmp_sort`. They use `priority ? 1 : 0` (priority=true→`'1'`), which requires **descending** sort to put priority items first. `ae_events__event_presentation.ts` DOES use `build_tmp_sort` (it overrides the generic encoding in its `specific_processor`). Do not apply the ascending rule to raw event or session sorts until those modules are migrated to `build_tmp_sort`.
16. **Service worker without `skipWaiting()` + `clients.claim()` silently serves stale code to long-lived tabs** — The default SvelteKit service worker template does NOT include these calls. Without them, a new SW installs in the background but waits in a **"waiting"** state until every tab running the old version is closed before it activates. Users who leave a page open all day (especially IDAA members in the Novi iframe on idaa.org) run old buggy JS indefinitely after a fix is deployed. 16. **`$` sigil on a plain prop value → `store_invalid_shape` at runtime** — when a parent passes
`prop={resolved_value}`, the child receives a plain JS value. Using `$prop` inside the child
tries to subscribe to it as a Svelte store and throws `store_invalid_shape: X is not a store
with a subscribe method`. This often happens in files migrated from Svelte 4 where `$lq__*`
usage was correct for the old store-subscription pattern. In Svelte 5, props are plain values:
```svelte
<!-- ❌ Wrong — treats prop as a Svelte store -->
{$lq__event_session_obj?.name}
<!-- ✅ Correct — prop is already the resolved value -->
{lq__event_session_obj?.name}
```
Also note: `PersistedState` stores (events module) use `.current` access, never the `$` sigil.
17. **`*_json` / `*_kv_json` DB columns start as `null`** — JSON blob columns (`cfg_json`,
`data_json`, `poc_kv_json`, etc.) are `null` in the database until first written. Two failure
modes:
- **Read crash:** `obj.poc_kv_json[poc_type]` throws `TypeError: can't access property "X",
poc_kv_json is null`. Fix: always use optional chaining: `obj.poc_kv_json?.[poc_type]`.
- **Write crash:** spreading `null` — `{ ...obj.poc_kv_json }` throws. Fix: initialize with
`{ ...(obj.poc_kv_json ?? {}) }` before writing any nested keys.
```ts
// ✅ Safe read
const bio_updated = obj.poc_kv_json?.[poc_type]?.biography_updated_on;
// ✅ Safe write
const kv = { ...(obj.poc_kv_json ?? {}) };
if (!kv[poc_type]) kv[poc_type] = {};
kv[poc_type]['biography'] = new_value;
await update_obj({ data_kv: { poc_kv_json: kv } });
```
18. **Service worker without `skipWaiting()` + `clients.claim()` silently serves stale code to long-lived tabs** — The default SvelteKit service worker template does NOT include these calls. Without them, a new SW installs in the background but waits in a **"waiting"** state until every tab running the old version is closed before it activates. Users who leave a page open all day (especially IDAA members in the Novi iframe on idaa.org) run old buggy JS indefinitely after a fix is deployed.
**Symptom that should trigger this check:** Bug reports from users that developers cannot reproduce. Developers constantly refresh and open/close tabs — the new SW activates immediately for them. End users with persistent tabs never get it. **Symptom that should trigger this check:** Bug reports from users that developers cannot reproduce. Developers constantly refresh and open/close tabs — the new SW activates immediately for them. End users with persistent tabs never get it.
@@ -536,4 +568,5 @@ Start here, then go deeper as needed:
| Electron / native launcher | `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` | | Electron / native launcher | `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` |
| Store migration plan | `documentation/PROJECT__Stores_Svelte5_Migration.md` | | Store migration plan | `documentation/PROJECT__Stores_Svelte5_Migration.md` |
| Exhibitor Leads module | `documentation/MODULE__AE_Events_Exhibitor_Leads.md` | | Exhibitor Leads module | `documentation/MODULE__AE_Events_Exhibitor_Leads.md` |
| Presentation Management module | `documentation/PROJECT__AE_Events_PressMgmt_Config_Cleanup.md` |
| Naming conventions | `documentation/AE__Naming_Conventions.md` | | Naming conventions | `documentation/AE__Naming_Conventions.md` |