mvc-kit 2.13.2 → 2.14.0

package/dist/react/use-subscribe-only.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-subscribe-only.js","names":[],"sources":["../../src/react/use-subscribe-only.ts"],"sourcesContent":["import { useSyncExternalStore, useRef } from 'react';\n\ninterface SubscribeOnlyRef {\n  target: { subscribe(cb: () => void): () => void };\n  version: number;\n  subscribe: (onStoreChange: () => void) => () => void;\n  getSnapshot: () => number;\n}\n\nconst SERVER_SNAPSHOT = () => 0;\n\n/**\n * Subscribe to a notification-only object (has subscribe() but no state).\n * Triggers React re-renders via version counter when the target notifies.\n * @internal\n */\nexport function useSubscribeOnly(\n  target: { subscribe(cb: () => void): () => void },\n): void {\n  const ref = useRef<SubscribeOnlyRef | null>(null);\n\n  if (!ref.current || ref.current.target !== target) {\n    const version = { current: ref.current?.version ?? 0 };\n    ref.current = {\n      target,\n      version: version.current,\n      subscribe: (onStoreChange: () => void) => {\n        return target.subscribe(() => {\n          version.current++;\n          ref.current!.version = version.current;\n          onStoreChange();\n        });\n      },\n      getSnapshot: () => version.current,\n    };\n  }\n\n  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);\n}\n"],"mappings":";;AASA,IAAM,wBAAwB;;;;;;AAO9B,SAAgB,iBACd,QACM;CACN,MAAM,MAAM,OAAgC,KAAK;AAEjD,KAAI,CAAC,IAAI,WAAW,IAAI,QAAQ,WAAW,QAAQ;EACjD,MAAM,UAAU,EAAE,SAAS,IAAI,SAAS,WAAW,GAAG;AACtD,MAAI,UAAU;GACZ;GACA,SAAS,QAAQ;GACjB,YAAY,kBAA8B;AACxC,WAAO,OAAO,gBAAgB;AAC5B,aAAQ;AACR,SAAI,QAAS,UAAU,QAAQ;AAC/B,oBAAe;MACf;;GAEJ,mBAAmB,QAAQ;GAC5B;;AAGH,sBAAqB,IAAI,QAAQ,WAAW,IAAI,QAAQ,aAAa,gBAAgB"}
+{"version":3,"file":"use-subscribe-only.js","names":[],"sources":["../../src/react/use-subscribe-only.ts"],"sourcesContent":["import { useSyncExternalStore, useRef } from 'react';\n\ninterface SubscribeOnlyRef {\n  target: { subscribe(cb: () => void): () => void };\n  version: number;\n  subscribe: (onStoreChange: () => void) => () => void;\n  getSnapshot: () => number;\n}\n\nconst SERVER_SNAPSHOT = () => 0;\n\n/**\n * Subscribe to a notification-only object (has subscribe() but no state).\n * Triggers React re-renders via version counter when the target notifies.\n * @internal\n */\nexport function useSubscribeOnly(\n  target: { subscribe(cb: () => void): () => void },\n): void {\n  const ref = useRef<SubscribeOnlyRef | null>(null);\n\n  if (!ref.current || ref.current.target !== target) {\n    const version = { current: ref.current?.version ?? 0 };\n    const entry: SubscribeOnlyRef = {\n      target,\n      version: version.current,\n      subscribe: (onStoreChange: () => void) => {\n        return target.subscribe(() => {\n          version.current++;\n          entry.version = version.current;\n          onStoreChange();\n        });\n      },\n      getSnapshot: () => version.current,\n    };\n    ref.current = entry;\n  }\n\n  useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);\n}\n"],"mappings":";;AASA,IAAM,wBAAwB;;;;;;AAO9B,SAAgB,iBACd,QACM;CACN,MAAM,MAAM,OAAgC,KAAK;AAEjD,KAAI,CAAC,IAAI,WAAW,IAAI,QAAQ,WAAW,QAAQ;EACjD,MAAM,UAAU,EAAE,SAAS,IAAI,SAAS,WAAW,GAAG;EACtD,MAAM,QAA0B;GAC9B;GACA,SAAS,QAAQ;GACjB,YAAY,kBAA8B;AACxC,WAAO,OAAO,gBAAgB;AAC5B,aAAQ;AACR,WAAM,UAAU,QAAQ;AACxB,oBAAe;MACf;;GAEJ,mBAAmB,QAAQ;GAC5B;AACD,MAAI,UAAU;;AAGhB,sBAAqB,IAAI,QAAQ,WAAW,IAAI,QAAQ,aAAa,gBAAgB"}

package/examples/react/AuthExample/src/components/AdminPage.tsx

@@ -3,6 +3,8 @@ import { AuthViewModel } from '../viewmodels/AuthViewModel';
 
 export function AdminPage() {
   const [state, vm] = useSingleton(AuthViewModel);
+  const { user } = state;
+  if (!user) return null; // AuthGuard renders this page only when signed in
 
   // Role check is done inside the page, not via a route wrapper.
   // This keeps routing simple and the access-denied message inline.
@@ -13,7 +15,7 @@ export function AdminPage() {
           <h2>Access Denied</h2>
           <p>
             You are signed in as <strong>{vm.displayName}</strong> with
-            the <span className={`badge badge-${state.user!.role}`}>{state.user!.role}</span> role.
+            the <span className={`badge badge-${user.role}`}>{user.role}</span> role.
           </p>
           <p>This page requires the <span className="badge badge-admin">admin</span> role.</p>
         </div>

package/examples/react/AuthExample/src/components/DashboardPage.tsx

@@ -3,6 +3,8 @@ import { AuthViewModel } from '../viewmodels/AuthViewModel';
 
 export function DashboardPage() {
   const [state, vm] = useSingleton(AuthViewModel);
+  const { user } = state;
+  if (!user) return null; // AuthGuard renders this page only when signed in
 
   return (
     <div className="page-content">
@@ -11,8 +13,8 @@ export function DashboardPage() {
       <div className="card" style={{ marginBottom: '1.5rem' }}>
         <h2 style={{ marginBottom: '0.5rem' }}>Welcome, {vm.displayName}!</h2>
         <p style={{ color: 'var(--color-text-secondary)' }}>
-          You are signed in as <strong>{state.user!.email}</strong> with
-          the <span className={`badge badge-${state.user!.role}`}>{state.user!.role}</span> role.
+          You are signed in as <strong>{user.email}</strong> with
+          the <span className={`badge badge-${user.role}`}>{user.role}</span> role.
         </p>
       </div>
 

package/examples/react/AuthExample/src/components/ProfilePage.tsx

@@ -3,7 +3,8 @@ import { AuthViewModel } from '../viewmodels/AuthViewModel';
 
 export function ProfilePage() {
   const [state, vm] = useSingleton(AuthViewModel);
-  const user = state.user!;
+  const { user } = state;
+  if (!user) return null; // AuthGuard renders this page only when signed in
 
   return (
     <div className="page-content">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mvc-kit",
-  "version": "2.13.2",
+  "version": "2.14.0",
   "description": "Zero-magic, class-based reactive ViewModel library",
   "type": "module",
   "main": "./dist/mvc-kit.cjs",

package/src/Model.md

@@ -386,11 +386,22 @@ The returned `FieldHandle` provides:
 
 ## Model Inside a ViewModel
 
-The typical pattern for a form page: the ViewModel handles async operations and coordination, the Model handles editing state.
+The typical pattern for a form: the ViewModel handles async operations and coordination, the Model handles editing state. There are two shapes, and the right choice depends on whether the form's initial data is already in hand.
+
+| If the initial data is... | Shape |
+|---|---|
+| **Available at construction** (create modal, edit modal taking an entity prop) | Create the Model in the **constructor** as `readonly`. Non-nullable, no guard. |
+| **Fetched by ID** after mount (edit page that loads from the server) | Declare it `\| null = null` and create it in `onInit()`. Component must guard. |
+
+> **Never** write `public model!: FormModel`. The `!` definite-assignment assertion lies to TypeScript about runtime state — first render runs before `onInit`, so `vm.model` is `undefined`, and `useField` / `useModel` crash with "Cannot read properties of undefined."
+
+### Shape 1 — Data available at construction
+
+The ViewModel receives everything it needs via `useLocal`'s initial state. Create the Model in the constructor so it exists from the first render onward.
 
 ```typescript
 interface EditState {
-  draft: UserState | null;
+  existing: UserState | null;
 }
 
 interface EditEvents {
@@ -398,7 +409,47 @@ interface EditEvents {
 }
 
 class EditUserViewModel extends ViewModel<EditState, EditEvents> {
-  public model!: UserFormModel;
+  // `readonly` refers to the *reference* — the model's state still changes via set().
+  public readonly model: UserFormModel;
+  private service = singleton(UserService);
+
+  constructor(initialState: EditState) {
+    super(initialState);
+    this.model = new UserFormModel(initialState.existing ?? INITIAL_FORM_STATE);
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    const result = await this.service.save(this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: result.id });
+  }
+
+  protected onDispose() {
+    this.model.dispose();
+  }
+}
+```
+
+```tsx
+function EditUserModal({ existing, onClose }: Props) {
+  const [, vm] = useLocal(EditUserViewModel, { existing });
+  const { loading: saving } = vm.async.save;
+
+  useEvent(vm, 'saved', onClose);
+
+  // No guard — vm.model is non-null from the first render.
+  return <EditUserForm model={vm.model} onSave={vm.save} saving={saving} />;
+}
+```
+
+### Shape 2 — Data fetched by ID
+
+Only an ID is known at construction; the entity is loaded in `onInit()`. The Model is nullable until the fetch resolves.
+
+```typescript
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model: UserFormModel | null = null;
   private service = singleton(UserService);
 
   protected async onInit() {
@@ -408,7 +459,7 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
   }
 
   async save() {
-    if (!this.model.valid) return;
+    if (!this.model || !this.model.valid) return;
     await this.service.update(this.userId, this.model.state, this.disposeSignal);
     this.model.commit();
     this.emit('saved', { id: this.userId });
@@ -420,8 +471,6 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
 }
 ```
 
-The component:
-
 ```tsx
 function EditUserPage() {
   const [state, vm] = useLocal(EditUserViewModel, { draft: null });

package/src/Service.md

@@ -92,7 +92,10 @@ class ConfigService extends Service {
   }
 
   getConfig(): AppConfig {
-    return this.config!;
+    if (!this.config) {
+      throw new Error('ConfigService not initialized — await init() before getConfig()');
+    }
+    return this.config;
   }
 }
 

package/src/react/components/DataTable.tsx

@@ -153,13 +153,9 @@ export function DataTable<T>({
   // ── Resolve props ──
   const resolvedSelection = selection ? resolveSelectionProp(selection) : undefined;
 
-  let resolvedSorts: readonly SortDescriptor[] | undefined;
-  let resolvedOnSort: ((key: string) => void) | undefined;
-  if (sort) {
-    const resolved = resolveSortProp(sort, onSort);
-    resolvedSorts = resolved.sorts;
-    resolvedOnSort = resolved.onSort;
-  }
+  const resolvedSort = sort ? resolveSortProp(sort, onSort) : undefined;
+  const resolvedSorts = resolvedSort?.sorts;
+  const resolvedOnSort = resolvedSort?.onSort;
 
   let displayItems = items;
   let paginationInfo: PaginationInfo | undefined;
@@ -171,8 +167,8 @@ export function DataTable<T>({
 
   // Selection: check indeterminate state
   const allKeys = resolvedSelection ? displayItems.map(item => keyOf(item)) : [];
-  const allSelected = resolvedSelection && allKeys.length > 0 && allKeys.every(k => resolvedSelection!.selected.has(k));
-  const someSelected = resolvedSelection && allKeys.some(k => resolvedSelection!.selected.has(k));
+  const allSelected = !!resolvedSelection && allKeys.length > 0 && allKeys.every(k => resolvedSelection.selected.has(k));
+  const someSelected = !!resolvedSelection && allKeys.some(k => resolvedSelection.selected.has(k));
 
   return (
     <div data-component="data-table" className={className}>
@@ -187,7 +183,7 @@ export function DataTable<T>({
                   ref={(el) => {
                     if (el) el.indeterminate = !!someSelected && !allSelected;
                   }}
-                  onChange={() => resolvedSelection!.onToggleAll(allKeys)}
+                  onChange={() => resolvedSelection.onToggleAll(allKeys)}
                   aria-label="Select all"
                 />
               </th>
@@ -208,13 +204,13 @@ export function DataTable<T>({
                   aria-sort={isSortable ? getAriaSortValue(col.key, resolvedSorts) : undefined}
                 >
                   {isSortable ? (
-                    <button type="button" onClick={() => resolvedOnSort!(col.key)}>
+                    <button type="button" onClick={() => resolvedOnSort(col.key)}>
                       {col.header}
                       {renderSortIndicator?.({
                         active: isActive,
                         direction: sortDesc?.direction ?? 'asc',
                         index: sortIndex,
-                        onToggle: () => resolvedOnSort!(col.key),
+                        onToggle: () => resolvedOnSort(col.key),
                       })}
                     </button>
                   ) : (
@@ -237,7 +233,7 @@ export function DataTable<T>({
                     <input
                       type="checkbox"
                       checked={!!isSelected}
-                      onChange={() => resolvedSelection!.onToggle(key)}
+                      onChange={() => resolvedSelection.onToggle(key)}
                       aria-label={`Select row ${key}`}
                     />
                   </td>

package/src/react/use-instance.ts

@@ -1,6 +1,8 @@
 import { useSyncExternalStore, useRef } from 'react';
 import type { Subscribable } from '../types';
 
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
 function hasAsyncSubscription(obj: unknown): obj is { subscribeAsync(cb: () => void): () => void } {
   return (
     obj !== null &&
@@ -27,24 +29,32 @@ interface InstanceRef<S> {
  * trigger React re-renders.
  */
 export function useInstance<S>(subscribable: Subscribable<S>): S {
+  if (__DEV__ && !subscribable) {
+    throw new Error(
+      'useInstance: received an undefined/null subscribable. ' +
+      'Make sure the instance is created synchronously (in a parent ViewModel\'s constructor or as a singleton) ' +
+      'before the component that calls useInstance renders. ' +
+      'If it\'s created in onInit(), guard the component with `if (!vm.child) return <Spinner />` first.',
+    );
+  }
   const ref = useRef<InstanceRef<S> | null>(null);
 
   if (!ref.current || ref.current.subscribable !== subscribable) {
     const version = { current: ref.current?.version ?? 0 };
-    ref.current = {
+    const entry: InstanceRef<S> = {
       version: version.current,
       subscribable,
       subscribe: (onStoreChange: () => void) => {
         const unsub1 = subscribable.subscribe(() => {
           version.current++;
-          ref.current!.version = version.current;
+          entry.version = version.current;
           onStoreChange();
         });
         let unsub2: (() => void) | undefined;
         if (hasAsyncSubscription(subscribable)) {
           unsub2 = subscribable.subscribeAsync(() => {
             version.current++;
-            ref.current!.version = version.current;
+            entry.version = version.current;
             onStoreChange();
           });
         }
@@ -52,6 +62,7 @@ export function useInstance<S>(subscribable: Subscribable<S>): S {
       },
       getSnapshot: () => version.current,
     };
+    ref.current = entry;
   }
 
   useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);

package/src/react/use-local.ts

@@ -133,7 +133,8 @@ export function useLocal<T extends Disposable, S = StateOf<T>>(
 
   // ── Effect: init + deferred cleanup ──
   useEffect(() => {
-    const instance = instanceRef.current!; // capture for cleanup closure
+    const instance = instanceRef.current;
+    if (!instance) return;
     mountedRef.current = true;
     if (isInitializable(instance)) {
       instance.init();

package/src/react/use-model.md

@@ -125,11 +125,20 @@ function UserForm() {
 
 ## Model Inside a ViewModel
 
-The typical form-page pattern: a [ViewModel](../ViewModel.md) handles async operations (load, save, delete) and coordination, while the Model handles the editing state. The ViewModel owns the Model and disposes it in `onDispose()`.
+The typical form pattern: a [ViewModel](../ViewModel.md) handles async operations (save, delete) and coordination, while the Model handles the editing state. The ViewModel owns the Model and disposes it in `onDispose()`. Which shape you use depends on whether the form's initial data is already available:
+
+| If the initial data is... | Shape |
+|---|---|
+| **Available at construction** (create modal, edit modal receiving an entity prop) | Create the Model in the **constructor** as `readonly`. Non-nullable, no guard. |
+| **Fetched by ID** after mount (edit page that loads from the server) | Declare it `\| null = null` and create it in `onInit()`. Component must guard. |
+
+> **Never** write `public model!: FormModel`. The `!` lies to TypeScript about runtime state — first render runs before `onInit`, `vm.model` is `undefined`, and `useField`/`useModel` crash. Pick one of the two shapes below.
+
+### Shape 1 — Data available at construction (preferred when applicable)
 
 ```typescript
 interface EditState {
-  draft: UserState | null;
+  existing: UserState | null;  // null → create, non-null → edit
 }
 
 interface EditEvents {
@@ -137,7 +146,45 @@ interface EditEvents {
 }
 
 class EditUserViewModel extends ViewModel<EditState, EditEvents> {
-  public model!: UserFormModel;
+  // `readonly` refers to the reference — the model's state still changes via set().
+  public readonly model: UserFormModel;
+  private service = singleton(UserService);
+
+  constructor(initialState: EditState) {
+    super(initialState);
+    this.model = new UserFormModel(initialState.existing ?? INITIAL_FORM_STATE);
+  }
+
+  async save() {
+    if (!this.model.valid) return;
+    const result = await this.service.save(this.model.state, this.disposeSignal);
+    this.model.commit();
+    this.emit('saved', { id: result.id });
+  }
+
+  protected onDispose() {
+    this.model.dispose();
+  }
+}
+```
+
+```tsx
+function EditUserModal({ existing, onClose }: Props) {
+  const [, vm] = useLocal(EditUserViewModel, { existing });
+  const { loading: saving } = vm.async.save;
+
+  useEvent(vm, 'saved', onClose);
+
+  // No guard — vm.model exists from the first render.
+  return <EditUserForm model={vm.model} onSave={vm.save} saving={saving} />;
+}
+```
+
+### Shape 2 — Data fetched by ID
+
+```typescript
+class EditUserViewModel extends ViewModel<EditState, EditEvents> {
+  public model: UserFormModel | null = null;
   private service = singleton(UserService);
 
   protected async onInit() {
@@ -147,7 +194,7 @@ class EditUserViewModel extends ViewModel<EditState, EditEvents> {
   }
 
   async save() {
-    if (!this.model.valid) return;
+    if (!this.model || !this.model.valid) return;
     await this.service.update(this.userId, this.model.state, this.disposeSignal);
     this.model.commit();
     this.emit('saved', { id: this.userId });

package/src/react/use-model.test.tsx

@@ -392,3 +392,89 @@ describe('type-level: useField rejects invalid field names', () => {
     _useField(model, 'age');
   });
 });
+
+describe('DEV assertions: undefined/null model', () => {
+  // React logs render errors to console.error even when an ErrorBoundary catches them.
+  // Silence the noise for these expected-throw tests.
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  class ErrorBoundary extends (require('react').Component as typeof import('react').Component)<
+    { children: import('react').ReactNode; onError: (e: Error) => void },
+    { err: Error | null }
+  > {
+    state = { err: null as Error | null };
+    static getDerivedStateFromError(err: Error) { return { err }; }
+    componentDidCatch(err: Error) { this.props.onError(err); }
+    render() {
+      return this.state.err ? null : this.props.children;
+    }
+  }
+
+  it('useField throws a diagnostic error when model is undefined', () => {
+    function Child({ model }: { model: any }) {
+      useField(model, 'name');
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child model={undefined} />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useField');
+    expect(caught!.message).toContain('undefined/null model');
+    expect(caught!.message).toContain('public model!');
+  });
+
+  it('useField throws when model is null', () => {
+    function Child({ model }: { model: any }) {
+      useField(model, 'name');
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child model={null} />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useField');
+  });
+
+  it('useModel throws when factory returns undefined', () => {
+    function Child() {
+      useModel(() => undefined as any);
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useModel');
+  });
+
+  it('useModelRef throws when factory returns undefined', () => {
+    function Child() {
+      useModelRef(() => undefined as any);
+      return null;
+    }
+    let caught: Error | null = null;
+    render(
+      <ErrorBoundary onError={e => { caught = e; }}>
+        <Child />
+      </ErrorBoundary>,
+    );
+    expect(caught).not.toBeNull();
+    expect(caught!.message).toContain('useModelRef');
+  });
+});

package/src/react/use-model.ts

@@ -4,6 +4,23 @@ import type { ValidationErrors } from '../types';
 import type { StateOf } from './types';
 import { isInitializable } from './guards';
 
+const __DEV__ = typeof __MVC_KIT_DEV__ !== 'undefined' && __MVC_KIT_DEV__;
+
+function assertModelExists(
+  model: unknown,
+  hookName: 'useModel' | 'useModelRef' | 'useField',
+): asserts model {
+  if (model) return;
+  throw new Error(
+    `${hookName}: received an undefined/null model. ` +
+    'This usually means the component rendered before the ViewModel finished creating the model. ' +
+    'Either (a) create the model in the ViewModel constructor when the initial data is available ' +
+    '(so it exists from the first render), or (b) if the model is created in onInit() after an async ' +
+    'fetch, guard the component render with `if (!vm.model) return <Spinner />` before calling this hook. ' +
+    'Do not use `public model!: FormModel` — the `!` lies to TypeScript about runtime state.',
+  );
+}
+
 /** Return type of `useModel`, providing state, validation, and model access. */
 export interface ModelHandle<S extends object, M extends Model<S>> {
   state: S;
@@ -22,25 +39,35 @@ export function useModel<M extends Model<any>>(
   const modelRef = useRef<M | null>(null);
   const mountedRef = useRef(false);
 
-  if (!modelRef.current || modelRef.current.disposed) {
-    modelRef.current = factory();
+  let model = modelRef.current;
+  if (!model || model.disposed) {
+    model = factory();
+    if (__DEV__) assertModelExists(model, 'useModel');
+    modelRef.current = model;
   }
 
   const modelSubscribe = useCallback(
-    (onStoreChange: () => void) => modelRef.current!.subscribe(onStoreChange),
+    (onStoreChange: () => void) => {
+      const m = modelRef.current;
+      return m ? m.subscribe(onStoreChange) : () => {};
+    },
     []
   );
   const modelSnapshot = useCallback(
-    () => modelRef.current!.state,
+    () => {
+      const m = modelRef.current;
+      if (!m) throw new Error('useModel: model accessed before creation');
+      return m.state;
+    },
     []
   );
   useSyncExternalStore(modelSubscribe, modelSnapshot, modelSnapshot);
 
   useEffect(() => {
+    const m = modelRef.current;
+    if (!m) return;
     mountedRef.current = true;
-    if (isInitializable(modelRef.current)) {
-      modelRef.current.init();
-    }
+    if (isInitializable(m)) m.init();
     return () => {
       mountedRef.current = false;
       setTimeout(() => {
@@ -51,8 +78,6 @@ export function useModel<M extends Model<any>>(
     };
   }, []);
 
-  const model = modelRef.current;
-
   return {
     state: model.state,
     errors: model.errors,
@@ -74,15 +99,18 @@ export function useModelRef<M extends Model<any>>(factory: () => M): M {
   const modelRef = useRef<M | null>(null);
   const mountedRef = useRef(false);
 
-  if (!modelRef.current || modelRef.current.disposed) {
-    modelRef.current = factory();
+  let model = modelRef.current;
+  if (!model || model.disposed) {
+    model = factory();
+    if (__DEV__) assertModelExists(model, 'useModelRef');
+    modelRef.current = model;
   }
 
   useEffect(() => {
+    const m = modelRef.current;
+    if (!m) return;
     mountedRef.current = true;
-    if (isInitializable(modelRef.current)) {
-      modelRef.current.init();
-    }
+    if (isInitializable(m)) m.init();
     return () => {
       mountedRef.current = false;
       setTimeout(() => {
@@ -93,7 +121,7 @@ export function useModelRef<M extends Model<any>>(factory: () => M): M {
     };
   }, []);
 
-  return modelRef.current;
+  return model;
 }
 
 /** Return type of `useField`, providing a single field's value, error, and setter. */
@@ -110,6 +138,7 @@ export function useField<S extends object, K extends keyof S>(
   model: Model<S>,
   field: K
 ): FieldHandle<S[K]> {
+  if (__DEV__) assertModelExists(model, 'useField');
   // Track the field value and error for comparison
   const getSnapshot = useCallback(() => {
     return {

package/src/react/use-subscribe-only.ts

@@ -21,18 +21,19 @@ export function useSubscribeOnly(
 
   if (!ref.current || ref.current.target !== target) {
     const version = { current: ref.current?.version ?? 0 };
-    ref.current = {
+    const entry: SubscribeOnlyRef = {
       target,
       version: version.current,
       subscribe: (onStoreChange: () => void) => {
         return target.subscribe(() => {
           version.current++;
-          ref.current!.version = version.current;
+          entry.version = version.current;
           onStoreChange();
         });
       },
       getSnapshot: () => version.current,
     };
+    ref.current = entry;
   }
 
   useSyncExternalStore(ref.current.subscribe, ref.current.getSnapshot, SERVER_SNAPSHOT);