OSIT-AE-App-Svelte/documentation/TODO__Agents.md

Frontend Agent Task List

Use this file to track steps for complex features or bug fixes. Status: Stable — ongoing development.

🚧 Upcoming High Priority

[Stores] Svelte 4 → Svelte 5 State Migration (prerequisite for Phase 2c)

The app uses svelte-persisted-store (Svelte 4 store contract) for all core persisted state (ae_loc, idaa_loc, ae_api, ae_sess, etc.). In Svelte 5 $effect, reading any field of a Svelte 4 store subscribes to the entire store — coarse-grained reactivity. This is the root cause of the IDAA Novi re-auth bug (2026-03-30): unrelated $ae_loc writes (e.g. iframe height, SWR cfg reload) triggered the Novi verification effect repeatedly.

Migration target: replace svelte-persisted-store with Svelte 5 $state-based persistence (e.g. runed PersistedState, or a lightweight custom wrapper). This gives fine-grained reactivity — only effects that actually read a changed field re-run.

Phased approach (do NOT do all at once):

• Phase A — Project plan + wrapper decision: Write PROJECT__Stores_Svelte5_Migration.md. Decide: runed library vs. custom $state + localStorage wrapper. Audit all store consumers. Identify stores in priority order. Estimate blast radius per store.

• Phase B — Core auth stores (highest impact, start here):

  • ae_loc (persisted) — auth flags, site cfg, UI state; ~471 consumer sites across 150+ files
  • idaa_loc (persisted) — Novi auth, IDAA query prefs These two cause the most reactive noise. Migrating them also unlocks Phase 2c (separate ae_auth store) since the callsite sweep is now required anyway.

• Phase C — Remaining persisted stores:

  • ae_api (persisted) — API config / JWT
  • ae_events_stores persisted entries (badges, launcher, leads, pres_mgmt loc stores)

• Phase D — Non-persisted writable stores:

  • ae_sess, idaa_sess, slct, slct_trigger, ae_auth_error, ae_trig, ae_snip, etc.
  • Lower urgency (no localStorage churn), but fine-grained reactivity still beneficial.

• Phase E — Phase 2c (unblocked after B): Split ae_loc into ae_auth + ae_app (see entry below — ~471 callsites, but sweep is cheap once already touching every consumer).

Project plan doc needed: Yes — scope is app-wide. Do NOT start Phase B without Phase A.

---

[Stores] Refactor — Phase 2c (deferred)

Phases 1, 2a, 2b are complete (see ✅ Completed below). One phase remaining:

• Phase 2c — Actual separate stores (ae_auth, ae_app): Requires touching ~471 $ae_loc.* auth-field read sites across 150+ files. Deferred until a Svelte runes migration of the store layer itself (touching every component anyway makes the callsite sweep cheap).

[Backend] Join event_location_id onto event_presenter API view

The event_presenter object currently has event_session_id but not event_location_id. When navigating from the Presenter View to the Launcher, the frontend has to do a secondary session lookup to discover the location (magic redirect in launcher base +page.svelte). Joining event_session.event_location_id into the presenter view/response would let the frontend pass the location directly in the Launcher URL without the extra lookup.

• Backend: add event_location_id (and event_location_id_random) to the event_presenter view or API response
• Frontend: add event_location_id to ae_EventPresenter type and properties_to_save; pass as events__launcher_id in presenter_page_menu.svelte

[Launcher] Active features (identified 2026-03-06)

• Font size cycler (Launcher sidebar): Font size cycler and light/dark toggle added to new menu_launcher_controls.svelte component; wired into launcher_menu.svelte. Visibility toggles (All Files / All Sessions) moved to same component and restyled to preset-tonal-tertiary. (2026-03-11)

• Minor Svelte warning: slct_event_location_id in menu_location_list.svelte — prop already has $bindable(null); stale comment in file updated. (2026-03-11)

[Svelte] State reference warnings

• svelte-check fully clean — 0 errors, 0 warnings. All 42 state_referenced_locally warnings fixed (2026-03-11). CSS @apply/@reference warnings in ae_idaa_comp__event_obj_id_edit.svelte also resolved — Tailwind utilities inlined, <style> block removed. (2026-03-16)

[TypeScript] svelte-check hidden errors — discovered 2026-03-27

HOW WE FOUND THIS: The @lucide/svelte 0.577.0 update (2026-03-10) dropped class from IconProps. Fixing it required a declare module '@lucide/svelte' augmentation. That augmentation was mistakenly placed in app.d.ts, which is a script-context declaration file (no export {}). In that context, declare module is an ambient replacement, not a merge — it wiped all icon exports from svelte-check's view, surfacing 1368 previously hidden errors. Once moved to src/lucide-augment.d.ts (a proper module file with export {}), the masking lifted and the real pre-existing errors became visible.

Lesson: A broken ambient declaration can silently hide unrelated errors. If svelte-check suddenly jumps to 0 errors, verify it's not because a bad .d.ts replaced a package's types.

Current state (2026-03-31): 32 errors, 0 warnings — all ModalProps.children.

• [flowbite-svelte] ModalProps.children — 31 errors across 26 files. The flowbite-svelte Modal component API changed; children is no longer a direct prop (now Svelte snippet-based). Affected files span journals, pres_mgmt, events/settings, and IDAA archives. Run npx svelte-check 2>&1 | grep ModalProps to get the current list. Fix pattern: replace children prop binding with Svelte snippet syntax per flowbite-svelte docs.

• [IDAA / Events] Audit default_qry_str coverage in other event search pages. The backend was updated 2026-03-31 to expose default_qry_str in API responses. Frontend fix applied to Recovery Meetings (+page.svelte + properties_to_save). Check all other event search pages that use db_events.event.filter() or a secondary post-API text filter — they may have the same mismatch (local searches name/description only while server uses default_qry_str). Start with: any route under /events/ or /idaa/ that has a full-text search input.

• [package.json] Remove orphaned ShadCN/bits-ui packages. shadcn-svelte and bits-ui remain in package.json but have no usages — src/lib/components/ui/ was removed 2026-03-27 (trashed to ~/tmp/gemini_trash/shadcn_components_ui_2026-03-27). Safe to remove both packages from dependencies when convenient.

[Badges] Remaining badge work before first live event

• Badge print controls UX polish: Scott has improvements in mind — TBD next session. File: ae_comp__badge_print_controls.svelte.

[Badges] Zebra ZC10L Hardware Testing

• Hardware test day complete. Real-world badge printing tested on Zebra ZC10L. Driver installed, test data set up, print verified. (2026-03-27)

[Leads] Exhibitor Lead Scanning — IN PROGRESS (demo-ready prep)

Module is substantially built as a PWA (no Electron). Core flow works end-to-end. Spec: documentation/PROJECT__AE_Events_Exhibitor_Leads_v3.md and _detail.md. Full audit: src/routes/events/[event_id]/(leads)/ and src/lib/ae_events/ae_events__exhibit*.ts.

What's working:

• Exhibit search/landing (/leads/) — SWR, local + API search, sort
• Exhibit detail page — 4-tab layout, sticky header with Add/List toggle, auto-refresh timer
• Tab 1 (Start): sign-in via shared passcode OR licensed user (email + passcode)
• Tab 2 (Add): QR scan (confirm mode — replaced rapid/qualify) + manual badge search; duplicate/re-enable detection on both
• Tab 3 (List): SWR lead list, licensee filter (All / My Leads), sort options, export button
• Tab 4 (Manage): admin tools, booth profile edit, passcode, license mgmt, custom questions config, app settings (refresh interval, clear IDB/localStorage, reload)
• Lead detail page: view/edit custom question responses, exhibitor notes (TipTap), priority/enable flags
• Export wired to V3 action endpoint /v3/action/event_exhibit/{id}/tracking_export (CSV/XLSX)

Remaining before demo:

• Export endpoint — V3 action endpoint confirmed live on backend (2026-03-16). Returns 403 if leads_api_access is not enabled on the exhibit — expected behavior. Export button now gated in UI: only renders when $lq__exhibit_obj?.leads_api_access === true. Enable via: PATCH /v3/crud/event_exhibit/{id} with { "leads_api_access": true }.
• allow_tracking gate — implemented (2026-03-16). QR scanner shows a warning card and blocks the add. Manual search shows a ShieldOff "Opt-Out" badge per row and guards add_as_lead. Opt-in model: allow_tracking must be explicitly true on the badge. Also added allow_tracking and agree_to_tc to ae_EventBadge in ae_types.ts. Demo note: ensure test badges have allow_tracking = true or no one can be added.
• Payment component — ae_comp__exhibit_payment.svelte fully implemented (2026-03-27). Reads Stripe config from $ae_loc.site_cfg_json (stripe_publishable_key, stripe_btn_1/3/6/10_license). License tier selector (1/3/6/10 users) with {#key} remount pattern for Stripe web component. 3 states: paid confirmation (priority=true), admin setup hint / "contact organizer" (no Stripe config), payment form. client_reference_id=exhibit_id. TypeScript declaration in app.d.ts. Stripe keys verified visible in $ae_loc.site_cfg_json on dev/demo site. Keys need validity check in Stripe dashboard.
• End-to-end smoke test — sign in with shared passcode, scan/search a badge, add a lead, view detail, add notes/responses, export CSV; verify on mobile (Chrome/Safari PWA)
• Install prompt — PWA install nudge implemented (2026-03-16). pwa_install.svelte.ts singleton captures beforeinstallprompt (Chrome/Android/desktop) and detects iOS Safari for manual "Share → Add to Home Screen" instructions. Reusable element_pwa_install_prompt.svelte placed on the Leads Start tab between the feature grid and sign-in. pwa_install.init() wired into root +layout.svelte; dismiss persists 7 days via localStorage. svelte-check: 0 errors.

[DevOps] Remaining deployment items

• Wire AE_APP_REPLICAS: docker-compose.yml line 147 already has scale: ${AE_APP_REPLICAS:-1}. (verified 2026-03-11)
• Archive ae_env_node_app: Archived as tar.gz under ~/OSIT_dev/backups/; old history/docs moved to ~/OSIT_dev/for_reference_only/. (2026-03-11)
• Build Optimization: Current state finalized. Local Gitea instance stood up at git.dgrzone.com (Docker, home server) — future: migrate repos from Bitbucket, verify Backblaze/restic backups cover Gitea data. (2026-03-11)
• Remote deploy script: aether_container_env/deploy.sh — SSH-triggered from workstation via npm run deploy:remote:test/prod. Handles git pull (ff-only) + docker build + restart. Tested and working on test env. (2026-03-25)
• .env.default cleanup: Removed 16 dead variables, added missing AE_NETWORK_NAME/CONTAINER_DOZZLE/AE_DOZZLE_PORT, parameterized all container names (CONTAINER_MARIADB, CONTAINER_PMA, CONTAINER_AE_OPS) with :-default fallbacks in compose. ("Dozzle" = log viewer container.) (2026-03-26)
• Prod deploy: Run npm run deploy:remote:prod (off-peak). Prerequisites: both repos pushed to Bitbucket ✓; verify .env.prod exists in /srv/apps/prod_aether_app_sveltekit/ on Linode before running. (2026-03-30)
• Bitbucket → SSH migration: Switched all three repos (aether_app_sveltekit, aether_container_env, aether_api_fastapi) to SSH remotes (git@bitbucket.org) on workstation. App passwords deprecated — SSH unaffected. (2026-03-27)
• Branch strategy cleanup: All environments (test, prod, bak) currently pull from same branches. deploy.sh defaults are ae_app_3x_llm / development — acceptable for now but should establish proper branch separation (e.g. main/master for prod).
• Tier 2 deploy (Gitea webhook): Push-triggered deploys via Gitea webhook → listener on Linode → deploy.sh. Deferred until Gitea usage is more established.

[General]

• Temp Cleanup: cleanup_tmp_files wired in launcher_background_sync.svelte; called at launcher startup. Confirmed working. (2026-03-11)
• window.print() for badge print button: Wired in ae_comp__badge_print_controls.svelte — increments count, fires window.print(), redirects to badge search. (done)
• Input Field Audit: Several input fields are missing name/id attributes or data-testid. Known examples: badge override fields in ae_comp__badge_obj_view.svelte; template name input in ae_comp__badge_template_form.svelte. Matters for: accessibility, autofill, label associations, and test targeting. (For tests, use getByLabel() rather than input[value*=...] which only checks the HTML attribute, not the Svelte-bound DOM property.)

✅ Completed (2026-03)

• [Stores] Phase 1 — Dead code cleanup (ae_stores.ts, ae_events_stores.ts, ae_idaa_stores.ts): removed ver_idb, stale comments, console.log lines, Stripe button block (zero consumers), personal Novi UUIDs, dead alternatives. Net: −202 lines across 3 files. svelte-check: 0 errors. (2026-03-16)
• [Stores] Phase 2a — Split defaults into domain sub-files: ae_stores__auth_loc_defaults.ts; ae_events_stores__badges/launcher/leads/pres_mgmt_defaults.ts. Spread-merged back into store structs — zero consumer changes. (2026-03-16)
• [Stores] Phase 2b — TypeScript interfaces for defaults sub-files: SiteCfgJson, AePerson, AeUser, AccessType, AuthLocState; BadgesLocState/SessState; SectionState, LauncherLocState/SessState; LeadsLocState/SessState, TmpLicense; PresMgmtLocState/SessState. svelte-check: 0 errors. (2026-03-16)
• [UI] Style Review Phase 1 & 2 complete — all non-frozen, non-IDAA routes migrated: FA→Lucide (events, pres_mgmt, core, badges, leads, hosted_files), variant-*→preset-* (all modules), code_to_html badge dict refactored to Lucide component map, FA CDN scoped to IDAA layout, global svg.lucide { display: inline } CSS rule added to fix icon inline flow. See documentation/PROJECT__AE_Style_Review.md. (2026-03-16)
• [UI] Pres Mgmt Phase 3 — FA→Lucide icon migration across all 24 pres_mgmt files. (2026-03-16)
• [IDAA] ae_idaa_comp__event_obj_id_edit.svelte — inlined Tailwind utilities, removed <style> block; eliminated all 23 @apply/@reference svelte-check warnings. (2026-03-16)
• [Badges] Badge print page svelte-check fix: extracted print CSS to static/ae-print-badge.css; fixed unclosed <script> tag in print/+page.svelte. (2026-03-16)
• [Svelte/Tests] svelte-check cleanup: fixed select_ref_badge_type $state() declaration; two <svelte:component> deprecations in launcher components; page.evaluate() two-arg pattern in badge_print_layout.test.ts. (2026-03-16)
• [Launcher] Hosted file download button require_auth prop — added require_auth?: boolean (default true) to ae_comp__hosted_files_download_button.svelte; all existing consumers unchanged. Launcher launcher_file_cont.svelte passes require_auth={false} so unauthenticated kiosk users can open/download files without being blocked. (2026-03-16)
• [Security] PUBLIC_AE_API_SECRET_KEY audit complete. Key is PUBLIC_* by design (always in client bundle). Highest-risk anonymous path uses limited-permission PUBLIC_AE_BOOTSTRAP_KEY. Full server-side migration not justified given JWT + account_id auth layers. Current state acceptable. (2026-03-11)
• [UX] Session Expired banner — ae_auth_error store wired to API helpers; root layout sets flag_expired on 401/403; non-blocking dismissible banner rendered. (2026-03-12)
• [UX] Access Denied UI standardized — element_access_denied.svelte created; /core layout, /events/settings, and /events/badges/review updated to use it. (2026-03-12)
• [Build] Rollup/Vite circular dependency warnings eliminated — manualChunks in vite.config.ts colocates all svelte/* internals into a single svelte-vendor chunk, preventing runtime.js / index-client.js split (~35 warnings gone). (2026-03-11)
• [Refactor] try_cache audit + sponsorship/event_file/hosted_file SWR alignment — removed vestigial try_cache params from generate_qr_code, ae_core_functions wrappers; added SWR fast/slow path to sponsorship loaders; changed event_file and hosted_file single-object loader defaults from false → true for consistency. (2026-03-11)
• [DevOps] Frontend + Backend unified into single aether_container_env Docker Compose. ae_app service live with healthcheck, single exposed port (AE_APP_NODE_PORT), internal ae_api networking. Deploy scripts in package.json both target ../aether_container_env/docker-compose.yml. (2026-03-10)
• [DevOps] /health endpoint live at src/routes/health/+server.ts. Docker HEALTHCHECK uses it. (2026-03-10)
• [UI] Dark mode color-scheme fix — html.dark/light { color-scheme } in app.css; all native browser controls now sync to app dark mode. (2026-03-10)
• [Launcher] Location select → session auto-load bug fixed via $derived.by() liveQuery pattern. (2026-03-10)
• [Svelte] state_referenced_locally warning fixes — 10 warnings resolved in IDAA archives/BB. (2026-03-09)
• [TypeScript] Sign In/Out TS errors fixed — user_id / person_id typed as string | null. (2026-03-09)
• [Tests] All badge data integrity and attendee workflow Playwright tests passing. Root causes documented in tests/README.md. (2026-03)
• [Badges] Badge print controls panel, QR code, duplex wiring, review form, print button, multi-word fulltext search, data-testid attributes. (2026-03)
• [UI] Firefly Theme + Pres Mgmt Visual Redesign (5 files). (2026-03-06)
• [Docs] UI Style Guidelines + Component Patterns docs created. (2026-03-06)
• [API] V3 Lookup system integration; Event File V3 mapping; event_session search 400-error fix. (2026-02/03)
• [API] All CRUD helpers on V3 /v3/crud/... paths. (2026-02)
• [Security] Purged x-aether-api-token; fixed misplaced CORS headers; Account ID Scavenging. (2026-02)
• [Security] Playwright integration tests replace verify_jwt_logic.js simulation tests. (2026-03)
• [Framework] AE_Obj_Field_Editor_V3 with Svelte 5 Runes. CRUD v2 fully retired. (2026-03-05)
• [IDAA] Bulletin Board and Recovery Meetings functionality verified. (2026-02)