docs(core-concepts.md): add section regarding object & element handles (#1871)

docs/README.md

@@ -6,7 +6,7 @@
     - [Pages and frames](./core-concepts.md#pages-and-frames)
     - [Selectors](./core-concepts.md#selectors)
     - [Auto-waiting](./core-concepts.md#auto-waiting)
-    - [Execution contexts](./core-concepts.md#execution-contexts)
+    - [Node.js and browser execution contexts](./core-concepts.md#node-js-and-browser-execution-contexts)
     - [Object & element handles](./core-concepts.md#object--element-handles)
 1. [Input](./input.md)
     - [Text input](./input.md#text-input)
@@ -47,4 +47,4 @@
 1. Continuous integration
     - Git Hub Action
     - Docker images
-    - Troubleshooting
+    - Troubleshooting

docs/core-concepts.md

@@ -162,7 +162,7 @@ await page.click('#search');
 
 <br/>
 
-## Execution contexts
+## Node.js and browser execution contexts
 
 Playwright scripts run in your Node.js environment. You page scripts run in the page environment. Those environments don't intersect, they are running in different virtual machines in different processes and potentially on different computers.
 
@@ -199,5 +199,47 @@ You can pass primitive types, JSON-alike objects and remote object handles recei
 
 ## Object & element handles
 
+Playwright has an API to create **node.js references** to DOM elements or objects inside the page. These
+references are called "handles" and live in node.js process, whereas the actual objects reside in browser.
+
+IMAGE PLACEHOLDER
+
+There are two types of handles:
+- [`JSHandle`](./api.md#class-jshandle) to reference any javascript objects in the page
+- [`ElementHandle`](./api.md#class-elementhandle) to reference DOM elements in the page
+
+Note that since any DOM element in the page is also a javascript object,
+Playwright's [`ElementHandle`](./api.md#class-elementhandle) extends
+[`JSHandle`](./api.md#class-jshandle).
+
+Handles Lifetime:
+- Handles can we aquired using page methods [`page.evaluteHandle`](./api.md#pageevaluatehandlepagefunction-arg), [`page.$`](./api.md#pageselector) or [`page.$$`](./api.md#pageselector-1) or
+  their frame counterparts [`frame.evaluateHandle`](./api.md#frameevaluatehandlepagefunction-arg), [`frame.$`](./api.md#frameselector) or [`frame.$$`](./api.md#frameselector-1).
+- Once created, handles will retain object from [grabage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management)
+- Handles will be **automatically disposed** once the page or frame they belong to navigates or closes.
+- Handles can be **manually disposed** using [`jsHandle.dispose`](./api.md#jshandledispose) method.
+
+Handles dereferencing can be done with [`jsHandle.evaluate`](./api.md#jshandleevaluatepagefunction-arg) method:
+
+```js
+const handle = await page.$('ul');
+await handle.evaluate(element => getComputedStyle(element).getPropertyValue('display'));
+```
+
+Alternatively, handles can be passed as arguments to [`page.evaluate`](./api.md#pageevaluatepagefunction-arg) function:
+```js
+const handle = await page.$('ul');
+await page.evaluate(element => getComputedStyle(element).getPropertyValue('display'), handle);
+```
+
+
+#### API reference
+- [`JSHandle`](./api.md#class-jshandle)
+- [`ElementHandle`](./api.md#class-elementhandle)
+- [`page.evaluteHandle`](./api.md#pageevaluatehandlepagefunction-arg)
+- [`page.$`](./api.md#pageselector)
+- [`page.$$`](./api.md#pageselector-1)
+- [`jsHandle.evaluate`](./api.md#jshandleevaluatepagefunction-arg)
+
 <br/>