refactor!: align browser v4 intialization flow to specs (#1040)

**Requirements**

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [x] I have validated my changes against all supported platform
versions

**Related issues**

sdk-1667

**Describe the solution you've provided**

- Introduced `start` method in `BrowserClient` to handle client
initialization.
- Replaced direct calls to identify with `setInitialContext` and `start`
for better context management.
- Updated example app to reflect changes in client initialization and
context handling.
- Added tests to ensure proper functionality of new initialization flow.

**Additional context**

- The main motiviation behind this change is to present a more organized
front on when a client is starting.
- I'll be making a task to push this behavior down to the shared client
code as an optional start and start adding a deprecated message on the
old flow.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds an explicit client start() flow and new createClient API (with
required initial context), updates initialization/identify behavior, and
refreshes tests, examples, and compat layer accordingly.
> 
> - **API/Initialization**:
> - Add `LDClient.start(options?)` returning
`LDWaitForInitializationResult`; cache promise; support `bootstrap` via
`start`/`identifyOptions`.
> - Replace `initialize(...)` with `createClient(clientSideId, context,
options)`; `makeClient` now requires an initial `LDContext`.
> - Disallow `identify` before `start` (returns `{ status: 'error' }`
and logs); initial `identify` is non-sheddable.
> - Normalize init statuses: `waitForInitialization` returns `{ status:
'complete' | 'failed' | 'timeout' }` (note: some tests updated from
`error`→`failed`).
> - Make `LDWaitForInitializationOptions.timeout` optional; add
`LDStartOptions`.
> - **BrowserClient**:
> - Track `_initialContext`, `_startPromise`, `_initializedPromise`;
preset flags from `bootstrap` before identify.
> - Update plugin registration/hook calls to run through new flow;
continue goal tracking logic, URL transformation for events.
> - **Compat (`/compat`)**:
> - `initialize(envKey, context, options)` now builds via
`makeClient(envKey, context, ...)`; immediately `start()` then perform
`identify` to mirror old behavior; re-export unchanged surface minus
`start`/`setInitialContext`.
> - **Examples/Contract Tests**:
> - Update example app and contract entity to use `createClient(...,
context)` and `client.start()` + `waitForInitialization()`.
> - **Tests**:
> - Revise unit tests to use `start()` and required initial context; add
cases for start idempotency, shedding order, bootstrap pre-eval, URL
filtering, waitForInitialization timing/failure.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
846ae61. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: joker23

packages/sdk/browser/__tests__/BrowserClient.plugins.test.ts

@@ -41,8 +41,10 @@ it('registers plugins and executes hooks during initialization', async () => {
 
   const platform = makeBasicPlatform();
 
+  const context: LDContext = { key: 'user-key', kind: 'user' };
   const client = makeClient(
     'client-side-id',
+    context,
     AutoEnvAttributes.Disabled,
     {
       streaming: false,
@@ -55,10 +57,7 @@ it('registers plugins and executes hooks during initialization', async () => {
 
   // Verify the plugin was registered
   expect(mockPlugin.register).toHaveBeenCalled();
-
-  // Now test that hooks work by calling identify and variation
-  const context: LDContext = { key: 'user-key', kind: 'user' };
-  await client.identify(context);
+  await client.start();
 
   expect(mockHook.beforeIdentify).toHaveBeenCalledWith({ context, timeout: undefined }, {});
 
@@ -134,6 +133,7 @@ it('registers multiple plugins and executes all hooks', async () => {
 
   const client = makeClient(
     'client-side-id',
+    { key: 'user-key', kind: 'user' },
     AutoEnvAttributes.Disabled,
     {
       streaming: false,
@@ -149,7 +149,7 @@ it('registers multiple plugins and executes all hooks', async () => {
   expect(mockPlugin2.register).toHaveBeenCalled();
 
   // Test that both hooks work
-  await client.identify({ key: 'user-key', kind: 'user' });
+  await client.start();
   client.variation('flag-key', false);
   client.track('event-key', { data: true }, 42);
 
@@ -200,6 +200,7 @@ it('passes correct environmentMetadata to plugin getHooks and register functions
 
   makeClient(
     'client-side-id',
+    { kind: 'user', key: '', anonymous: true },
     AutoEnvAttributes.Disabled,
     {
       streaming: false,
@@ -281,6 +282,7 @@ it('passes correct environmentMetadata without optional fields', async () => {
 
   makeClient(
     'client-side-id',
+    { kind: 'user', key: '', anonymous: true },
     AutoEnvAttributes.Disabled,
     {
       streaming: false,