[mvilacad]

Closes #618

Regression test (written first)

packages/ui/tests/theme-order.test.ts: in the BUILT HTML of each consumer path (Kit, Vite, Astro), every theme script (__caTheme, __caSiteBoot) comes before the first <style> / <link rel="stylesheet">. The same rule runs on every built site page in site/tests/dist-html.spec.ts.

• Fails on origin/main (bun test packages/ui/tests/theme-order.test.ts, with only the test and the boot markup it imports added to a clean origin/main checkout):

error: expect(received).toEqual(expected)
- []
+ [
+   "__caTheme: script at 7044, after the first stylesheet at 304",
+   "__caSiteBoot: no script in <head>",
+ ]
(fail) Astro: caUI puts the theme before every stylesheet, bundled or inline > the built page has every theme script ahead of its inlined CSS
 4 pass
 1 fail

• Passes on this branch:

 5 pass
 0 fail
 11 expect() calls
Ran 5 tests across 1 file.

Change

The theme script ran behind ~700 KB of inlined CSS, so a slow link painted the default theme first. caUI now emits the theme (and the site boot) first in <head>, before any stylesheet; storage-blocked and share-URL paths wear the target theme on first paint.

Checklist

• bun run validate passes (pre-push)
• Changeset
• Docs updated