From 6c822bc466caa8d786abe600b02768f26a7adc02 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Mon, 22 Jun 2026 19:04:52 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20add=20mistake=20#19=20=E2=80=94=20optio?=
 =?UTF-8?q?nal=20TypeScript=20params=20break=20vite=20build=20SSR?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the param?: Type pattern that esbuild mishandles in .svelte
files (strips the type but leaves ?, producing invalid JavaScript). Adds
the full write-up to REFERENCE__Common_Agent_Mistakes.md and a summary
entry #10 to BOOTSTRAP__AI_Agent_Quickstart.md §7.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../BOOTSTRAP__AI_Agent_Quickstart.md         |  3 ++
 .../REFERENCE__Common_Agent_Mistakes.md       | 46 +++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/documentation/BOOTSTRAP__AI_Agent_Quickstart.md b/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
index f4ab7027..d07125fa 100644
--- a/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
+++ b/documentation/BOOTSTRAP__AI_Agent_Quickstart.md
@@ -308,6 +308,9 @@ Read this section first, then open the reference doc when your task touches one
    field, SWR-await-after-write races, and stateful/conditional sync gates that desync local
    state from history rather than current config. See the Pres Mgmt Config sync overhaul
    (2026-06-16) in `PROJECT__AE_Events_PressMgmt_Config_Cleanup.md` for the full incident.
+10. **`param?: Type` in `.svelte` function/snippet parameters** — breaks `vite build` (SSR step)
+    silently: dev server is fine, Docker/production builds fail with "Expected ',', got '?'".
+    Use `param: Type | undefined = undefined` instead. See mistake #19 in the reference doc.
 
 The reference doc also includes a short archive list for older, less-relevant historical incidents.
 
diff --git a/documentation/REFERENCE__Common_Agent_Mistakes.md b/documentation/REFERENCE__Common_Agent_Mistakes.md
index 258c5c0f..e4f36ef8 100644
--- a/documentation/REFERENCE__Common_Agent_Mistakes.md
+++ b/documentation/REFERENCE__Common_Agent_Mistakes.md
@@ -248,6 +248,52 @@ function-level gate.
 the gate (sync unconditionally) loses any real behavior — query production data for whether
 the gate is ever actually in the "off" state before assuming it needs to exist.
 
+### 19) `param?: Type` in `.svelte` function or snippet parameter positions
+
+**Impact:** `vite build` SSR step fails with "Expected ',', got '?'" — Docker builds and
+production deploys break. Dev server is unaffected (different code path), so the error is
+invisible in local development and only surfaces in CI/CD or the first clean Docker build.
+
+**What happened:** Source files used TypeScript optional-parameter syntax (`param?: Type`)
+inside `.svelte` `<script lang="ts">` functions and `{#snippet}` parameter lists. esbuild
+(Vite's dep pre-bundler/SSR transform) strips `: Type` from the type annotation but leaves
+the `?` marker, producing `param?` — which is invalid JavaScript. Rollup then fails to parse
+the compiled output, showing the original `.svelte` line number via source maps.
+
+Five occurrences were found and fixed in 2026-06 across:
+`reports_file_downloads.svelte`, `ae_comp__journal_entry_obj_id_view.svelte`,
+`ae_comp__modal_journal_entry_config.svelte`, `launcher_file_cont.svelte`,
+`ae_comp__badge_print_controls.svelte` (Svelte 5 `{#snippet}` param).
+
+**Rule:** Never write `param?: Type` in function or snippet parameter positions inside
+`.svelte` files. Use `param: Type | undefined = undefined` instead — this preserves the
+same runtime behavior (calling without the argument passes `undefined`) and produces valid
+JavaScript after TypeScript stripping.
+
+```ts
+// ❌ Breaks vite build (SSR environment):
+function clean_part(s: any, max?: number): string { ... }
+{#snippet field_actions(on_save: () => void, on_revert?: () => void)}
+
+// ✅ Correct:
+function clean_part(s: any, max: number | undefined = undefined): string { ... }
+{#snippet field_actions(on_save: () => void, on_revert: (() => void) | undefined = undefined)}
+```
+
+This restriction applies **only inside `.svelte` files** — TypeScript `.ts` files are
+processed by the TypeScript compiler directly and handle `?: Type` correctly. Interface and
+type alias blocks inside `<script lang="ts">` are also fine (the Svelte compiler handles
+those natively); the restriction is only for runtime function/snippet parameter lists.
+
+Note: `scripts/postinstall.mjs` applies the same fix to flowbite-svelte's published dist
+files, which ship with TypeScript optional params in function signatures. That script needs
+to be maintained whenever flowbite-svelte is updated — check with:
+`grep -rn "?:" node_modules/flowbite-svelte/dist/ | grep "function\|=>"`.
+
+**Verify:** After writing any new function or `{#snippet}` in a `.svelte` file, scan for
+`\w\?:` in the parameter list. Run `npm run build:dev` locally before any Docker build or
+deploy — it will catch this within seconds.
+
 ---
 
 ## Archived Historical Items (Pruned)