Realms, globals & WindowProxy

Each page gets its own realm

A web page can hold more than one place where JavaScript runs. The page itself is one. Each iframe is another. An iframe is a small page shown inside a bigger page, such as a video player or a payment form.

Each of these places has its own realm. A realm is one complete JavaScript world. It has:

• a global object: the object that holds all the global names. In a page it is window, and you can always reach it as globalThis;
• its own built-ins: the ready-made objects JavaScript gives you, such as Array, Object, and Function.

1globalThis.lessonName = "realms";2console.log(globalThis.lessonName);

Line 1 stores a property called lessonName on this realm's global object. Line 2 reads it back and prints realms. An iframe has a different global object, so it does not get this property.

1globalThis.cartName = "parent cart";2const frameGlobal = { cartName: "frame cart" };3 4console.log(globalThis.cartName);5console.log(frameGlobal.cartName);6 7// A real iframe has its own global object. This plain object only stands in for it.

Line 1 stores cartName on the page's global object. Line 2 makes a plain object, frameGlobal. It stands in for an iframe's global object, so the example can run here. Line 4 prints parent cart. Line 5 prints frame cart. In a real browser, an iframe gives you a second global object like this.

So realms are kept apart. A name you put on one global object does not show up in another frame. Frames can still work together, but only on purpose. There are two ways, and you will see both later:

• reach into the other frame directly, which is allowed only when both pages come from the same site;
• send the other frame a message.

You may read about ShadowRealm. It is a proposal: a suggested new JavaScript feature that the standards group, TC39, is still discussing. Browsers don't ship it yet, so this lesson does not use it. An iframe is a real realm in browsers today. It also has its own page and its own address rules, which ShadowRealm would not have.

Realms matter when a page puts something inside an iframe: a checkout, a code editor, a preview, or an older app. Each frame runs normal JavaScript. But each frame has its own built-ins and its own global names. The previous lesson, Bindings: how DOM objects exist in JavaScript, shows how browser objects appear inside one realm.

The table below lists four words this lesson uses. Read each row as: the word, what it means, and an example.

Each iframe has its own built-ins

The spec (the official rule book for JavaScript and the web) calls a realm's built-ins its intrinsics. They include the constructors, such as Array. A constructor is a function that makes new objects.

Each constructor has a prototype. A prototype is a shared object that every value the constructor makes links back to. For Array, it is Array.prototype, where methods like push live.

The page's Array and an iframe's Array do the same job. But they are two different objects.

1const frame = document.createElement("iframe");2document.body.append(frame);3 4const FrameArray = frame.contentWindow.Array;5const list = new FrameArray("tea");6 7console.log(list instanceof Array);8console.log(Array.isArray(list));

Line 1 makes an empty iframe. Line 2 adds it to the page, so the iframe gets its own window. frame.contentWindow is that window. Line 4 reads the iframe's Array. Line 5 uses it to make a list. Line 7 prints false. Line 8 prints true.

Why false? list instanceof Array asks: "Does list link back to this page's Array.prototype?" It does not. It links back to the iframe's Array.prototype.

Array.isArray(list) asks a different question: "Is this value an array at all?" The answer is the same in every realm.

Try this example in the console of a normal page you control. It will not work in this lesson's editor. The editor runs your code in a locked-down frame with no site address of its own. That frame may not read even an empty iframe's contentWindow.Array, so it throws a SecurityError.

WindowProxy: a reference that survives a new page

A frame can load a new page. This is called navigation. Each new page gets a fresh global object, a new Window.

So what do you hold when you save frame.contentWindow? Not the Window itself. You hold a WindowProxy. A WindowProxy is a stand-in that passes each request on to whatever page the frame shows right now.

The spec calls the frame itself a browsing context: the place that shows one page at a time. The names contentWindow, parent, and frames all give you a WindowProxy.

1const frame = document.querySelector("iframe");2const room = frame.contentWindow;3 4console.log(room === frame.contentWindow);5frame.src = "/next-page";6console.log(room === frame.contentWindow);

Line 2 saves the frame's window in room. Line 4 prints true. Line 5 sets frame.src, which starts loading a new page. Line 6 prints true again, even before the new page has finished loading. This example is for reading only, because this lesson has no /next-page to load.

The main idea: room stays useful while the page inside the frame, and its Window, change.

Four realm names the spec uses

Sometimes the spec must pick one realm out of several. For example: when a page calls a function from a frame, whose settings apply? The HTML spec has four names for this. They solve rare edge cases. Most of the time you only need two of them: current and relevant.

1const frame = document.querySelector("iframe");2const printInFrame = frame.contentWindow.print;3printInFrame.call(frame.contentWindow);

Line 1 finds a frame. Line 2 reads the frame's print method. Line 3 calls it with .call(frame.contentWindow). .call() runs a function and sets the object it works on (its this). Here that object is the frame's window.

This one short call already involves two realms: the page's and the frame's. The four names below let the spec say exactly which one it means.

• Entry realm: the realm of the script that started the work that is running now.
• Incumbent realm: the realm of the page code that ran most recently, or that set up the callback running now. A callback is a function you hand over to be called later.
• Current realm: the realm of the function running right now.
• Relevant realm: the realm a browser object belongs to, usually the realm that made it.

For example, a method called on a frame's DOM object usually uses that object's relevant realm, which is the frame's realm. The spec writers tell new specs to avoid entry and incumbent where they can. Those two depend on the history of calls and callbacks, which is hard to follow.

1const callback = {2  entry: "the script that began this work",3  incumbent: "the author code that scheduled it",4  current: "the function running now",5  relevant: "the realm of the platform object",6};7 8console.log(callback.current);9console.log(callback.relevant);10 11// These notes only help you remember the names. They don't read real realms.

Lines 1 to 6 store one short note for each name. Line 8 prints the function running now. Line 9 prints the realm of the platform object. "Platform object" is the spec's word for a browser object, such as an element.

This is not a browser feature that shows hidden realms. It is only a way to keep the four names apart while you read a spec.

When your code calls a method, start with the object you call it on. A DOM node that belongs to a frame brings its relevant realm along. The current realm is simply the realm of the function that is running at that moment.

Why instanceof fails for a frame's array

A cross-realm object is a value made in one realm and used in another. Arrays show this best. Both realms have a name Array, but the two names point to different constructor objects.

1const frame = document.createElement("iframe");2document.body.append(frame);3const FrameArray = frame.contentWindow.Array;4const parentArray = ["tea"];5const frameArray = new FrameArray("tea");6 7console.log(parentArray instanceof Array);8console.log(frameArray instanceof Array);9console.log(Array.isArray(frameArray));

Lines 1 to 3 make an iframe and read its Array. Line 4 makes a normal page array. Line 5 makes a frame array.

• Line 7 prints true, because the page made that array.
• Line 8 prints false, because the frame made that array.
• Line 9 prints true, because Array.isArray works across realms.

This does not mean instanceof is broken. It checks whether a value links back to one exact prototype. That is useful when you really mean "made by this exact constructor". When you only need to know "is this an array?" and the value may come from another realm, use Array.isArray.

1const frameArray = ["tea"];Run2Object.setPrototypeOf(frameArray, null);3 4const parentThinksItIsAnArray = frameArray instanceof Array;5const parentRecognizesAnArray = Array.isArray(frameArray);6 7console.log(parentThinksItIsAnArray);8console.log(parentRecognizesAnArray);

The step-through can't use a real iframe, so it uses a stand-in. Line 2 takes a normal array and removes its link to any prototype. Then instanceof gives false, and Array.isArray still gives true. A real iframe array links to the iframe's own prototype instead. To see that for real, run the earlier example in a normal page's console.

Compare two realms

The playground has two realms, the page and an iframe, and one array. Pick which realm makes the array. Then pick which realm's instanceof Array check runs. Reset goes back to the most useful case: the iframe makes the array, and the page checks it.

1const frameArray = ["tea"];2Object.setPrototypeOf(frameArray, null);3 4const parentThinksItIsAnArray = frameArray instanceof Array;5const parentRecognizesAnArray = Array.isArray(frameArray);6 7console.log(parentThinksItIsAnArray);8console.log(parentRecognizesAnArray);

Every choice gives true for Array.isArray. That is the point. "This value is an array" and "this value came from this realm's Array" are two different facts.

Reading another frame: same origin only

An origin is the start of a web address: the scheme, the host name, and the port. For example, https://shop.example is an origin.

The same-origin policy is the browser rule that decides when one page may read another page directly:

• Frames from the same origin can read each other's page and JavaScript objects.
• Frames from different origins (cross-origin) cannot read normal properties such as document. If you try, the browser throws a SecurityError.

1const frame = document.createElement("iframe");2frame.onload = () => {3  console.log(frame.contentWindow.document.body.textContent);4};5frame.srcdoc = "<p>Same-origin frame</p>";6document.body.append(frame);

Line 1 makes an iframe. Lines 2 to 4 set up an onload function, which runs once the frame's page has loaded. Line 5 sets srcdoc, which gives the frame its HTML directly as text. Line 6 adds the frame to the page.

When the frame loads, the function reads the frame's page text and prints Same-origin frame. This works because a srcdoc page counts as the same origin as your page. Try it in the console of a normal page you control. This lesson's editor is a locked-down frame and blocks reads from contentWindow.

Cross-origin windows still allow a few safe actions. A page can call postMessage on them. It can also set a cross-origin frame's location to send it to a new address. But it cannot look inside the other page. See Windows and frames for more on frames.

1const frame = document.querySelector("iframe");2 3window.addEventListener("message", (event) => {4  console.log(event.data);5});6 7frame.contentWindow.postMessage({ type: "cart", count: 3 }, "*");

postMessage sends a message to another window. The other window gets it as a message event. Line 3 starts listening for messages. Line 7 sends plain data to the frame.

The "*" at the end of line 7 means "any origin may receive this". In real code, put the receiver's exact origin there instead. When a message arrives, check event.origin (who sent it) and the shape of the data before you act on it.

1const event = {2  origin: "https://checkout.example",3  data: { type: "order-ready", id: "tea-3" },4};5 6const isExpected = event.origin === "https://checkout.example" && event.data.type === "order-ready";7console.log(isExpected);8 9// Check where a message came from and what it holds before you use it.

Lines 1 to 4 describe one message that arrived. Line 6 checks two things: the origin it came from, and its type. Line 7 prints true only for the expected checkout message. Real code should ignore a message from an unknown origin, or with unknown data, before it changes a cart or an account.

Copying and moving data between frames

Often a frame does not need to reach into another frame. It only needs to send data. There are two ways to send it:

• Structured clone makes a full, separate copy of the data. Values it can copy are called serializable.
• A transfer moves the data instead of copying it. Values that can be moved are called transferable.

postMessage uses structured clone for you. You can also call it yourself with structuredClone(value).

1const cart = { item: "tea", count: 3 };2const copy = structuredClone(cart);3 4copy.count = 4;5console.log(cart.count);6console.log(copy.count);

Line 1 makes the original cart. Line 2 copies it. Line 4 changes only the copy. Lines 5 and 6 print 3 then 4. So the two objects are separate.

1const order = { id: "tea", count: 3 };2const copy = structuredClone(order);3copy.count = 4;4 5console.log(order.count);6console.log(copy.count);7 8// The copy is a new object. It shares nothing with the original.

Line 1 makes an order. Line 2 makes the copy. Line 3 changes the copy. Lines 5 and 6 still print 3 then 4. A copy is useful when the sender and the receiver should each be free to change their own data.

1const buffer = new ArrayBuffer(8);2const moved = structuredClone(buffer, { transfer: [buffer] });3 4console.log(buffer.byteLength);5console.log(moved.byteLength);

An ArrayBuffer is a block of raw bytes, such as the contents of a file. Its byteLength tells you how many bytes it holds.

• Line 1 makes a buffer of 8 bytes.
• Line 2 puts buffer in the transfer list, so its bytes move to moved.
• Line 4 prints 0. The old buffer is now empty. The spec calls it detached.
• Line 5 prints 8, because moved now holds the bytes.

1const buffer = new ArrayBuffer(8);Run2const moved = structuredClone(buffer, { transfer: [buffer] });3 4console.log(buffer.byteLength);5console.log(moved.byteLength);

1const cart = { save() {} };2 3try {4  structuredClone(cart);5} catch (error) {6  console.log(error.name);7}

Line 1 makes an object that holds a function, save. Line 4 tries to copy it inside try. If the code in try fails, the catch part runs and gets the error. Line 6 prints the error's name, DataCloneError.

Functions and DOM nodes cannot be copied. A function is code, not plain data. A DOM node belongs to one page and only makes sense there.

The table below sums up the four cases. Read each row as: the case, what happens, and when to use it.

1const parentSymbol = Symbol.for("cart-status");2const otherRealmSymbol = Symbol.for("cart-status");3 4console.log(parentSymbol === otherRealmSymbol);5 6// Symbol.for uses one shared list, but each realm has its own Array.

A symbol is a unique value, often used as a property key. Symbol.for(key) looks up a symbol by name in the global symbol registry, a shared list of named symbols. Lines 1 and 2 ask that list for the same name. Line 4 prints true.

Remember this exception. Each realm has its own Array. But realms in the same agent share one symbol registry. An agent is the spec's name for one thread that runs JavaScript. A page and the frames it can read directly share one agent.

Choosing a safe way to connect frames

First ask: do these two pages really need to reach into each other? Same-origin pages can share objects directly. But then each page depends on the other page's inner details. A message makes the shared data easy to see, and it also works across origins.

A value may come from a browser extension, an iframe, or another window. Then don't check its type only with instanceof. Use checks that work in any realm: for example Array.isArray for arrays, a type property that you check by name, or a check of every field for messages you don't trust.

• To talk across origins, use postMessage with the receiver's exact origin.
• Before you use a message, check where it came from and the shape of its data.
• Transfer a large buffer when only the receiver needs it. Copy the data when both sides need their own.
• Use Array.isArray when an array may come from another realm.

Common misconceptions

• “An iframe is only something you see.” It also has its own page, its own global object, and its own realm.
• “window is always one object.” A reference to another frame's window is usually a WindowProxy. It keeps working after the frame loads a new page.
• “instanceof recognizes every array.” It checks one realm's Array.prototype. An array from another realm fails that check.
• “Same origin means the frames share everything.” Same origin lets frames read each other directly. But their realms and their Array constructors are still separate.
• “structuredClone can copy anything.” Functions and DOM nodes make it throw a DataCloneError.

The table below lists words that are easy to mix up. Read each row as: the word, what it means, and what it is not.

Practice exercises

Array.isArray(value)

const buffer = new ArrayBuffer(4);
const moved = structuredClone(buffer, { transfer: [buffer] });
console.log(buffer.byteLength, moved.byteLength);

frame.contentWindow.postMessage(message, targetOrigin);

Check your understanding

The quiz checks four things that are easy to mix up:

• which realm made a value,
• what a saved frame reference reaches,
• whether two origins match,
• whether data is copied or moved.

Key takeaways

• Every page and every iframe has its own realm: its own global object and its own built-ins.
• A saved frame reference is a WindowProxy. It keeps working after the frame loads a new page.
• For an array from another realm, instanceof Array is false, but Array.isArray is true.
• Of the four realm names, you mostly need two: the current realm and an object's relevant realm.
• Same-origin frames can read each other directly. Cross-origin frames should talk with postMessage.
• Structured clone copies plain data. A transfer moves values such as an ArrayBuffer and leaves the old one empty.

Coming next: the browser security model. It shows how the same-origin policy and the browser's separate processes keep these worlds safe from each other.