diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fecd6aaa1..e7806a628 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,6 +39,28 @@ bun run format:check    # Check formatting without writing
 
 Git hooks (via [lefthook](https://github.com/evilmartians/lefthook)) run automatically after `bun install` and enforce linting + formatting on staged files before each commit.
 
+#### Type-safety conventions
+
+We aim for honest types — code that lies to the compiler eventually lies to users. The underlying convention is:
+
+- **Avoid `any`.** Use `unknown` and narrow it where possible.
+- **Avoid `as T` type assertions.** They suppress type-checker warnings without telling the compiler anything new. Prefer:
+  - Type guards (`function isFoo(x): x is Foo`)
+  - `instanceof` / `typeof` narrowing
+  - Centralized narrowing helpers (e.g. `resolveIframe`)
+  - Properly-typed interfaces at the source
+- **Acceptable `as` use, with a comment explaining why:**
+  - `as const` — literal narrowing; always safe
+  - `as unknown as T` — explicit double-cast at hard type-system boundaries (e.g. parsing untrusted JSON, FFI/postMessage). Pair with a one-line justification.
+- **Avoid `!` non-null assertions** outside of post-`if`-checked code paths. Use `??` defaults or guard clauses instead.
+
+If you must add a cast, add a comment:
+
+```ts
+// `postMessage` data is `unknown`; the runtime guarantees this shape.
+const event = data as unknown as RuntimeEvent;
+```
+
 ## Pull Requests
 
 - Use [conventional commit](https://www.conventionalcommits.org/) format for **all commits** (e.g., `feat: add timeline export`, `fix: resolve seek overflow`). Enforced by a git hook.
diff --git a/docs/packages/player.mdx b/docs/packages/player.mdx
index b76c50d90..18f4eb23d 100644
--- a/docs/packages/player.mdx
+++ b/docs/packages/player.mdx
@@ -155,6 +155,66 @@ player.addEventListener('ready', () => player.play());
 document.getElementById('player-container').appendChild(player);
 ```
 
+## Advanced: iframe access
+
+The composition runs inside a sandboxed `<iframe>` in the player's Shadow DOM. For most use cases you don't need direct access — the JavaScript API and events above are sufficient. But if you're building an editor, recorder, or custom timeline on top of the player, you'll need to inspect the composition's DOM or read its `__player` / `__timelines` runtime objects. The `iframeElement` getter exposes the inner iframe for these consumers:
+
+```js
+const player = document.querySelector('hyperframes-player');
+const iframe = player.iframeElement;
+
+// Reach into the composition's DOM
+iframe.contentDocument.querySelectorAll('[data-composition-id]');
+
+// Read the runtime (GSAP timelines, element registry, etc.)
+iframe.contentWindow.__timelines;
+```
+
+This is the canonical way to bridge the player into editor tools like [`@hyperframes/studio`](/packages/studio). The studio exports a `resolveIframe` helper that handles both direct iframe refs and web-component refs:
+
+```ts
+import { useTimelinePlayer, resolveIframe } from '@hyperframes/studio';
+
+const { iframeRef } = useTimelinePlayer();
+const player = document.createElement('hyperframes-player');
+player.setAttribute('src', src);
+container.appendChild(player);
+
+// Forward the inner iframe so useTimelinePlayer can drive play/pause/seek.
+iframeRef.current = resolveIframe(player);
+```
+
+### React: declarative ref pattern
+
+If you prefer JSX over imperative element creation, attach a ref to the web component and resolve the iframe inside an effect:
+
+```tsx
+import '@hyperframes/player';
+import type { HyperframesPlayer } from '@hyperframes/player';
+import { useTimelinePlayer, resolveIframe } from '@hyperframes/studio';
+
+function StudioPreview({ src }: { src: string }) {
+  const { iframeRef, onIframeLoad } = useTimelinePlayer();
+  const playerRef = useRef<HyperframesPlayer>(null);
+
+  useEffect(() => {
+    iframeRef.current = resolveIframe(playerRef.current);
+  });
+
+  return (
+    <hyperframes-player
+      ref={playerRef}
+      src={src}
+      onLoad={onIframeLoad}
+    />
+  );
+}
+```
+
+<Warning>
+  **Common gotcha** — if you pass the `<hyperframes-player>` element itself (not `iframeElement`) into a hook or API that expects an `<iframe>`, every `.contentWindow` / `.contentDocument` access returns `null` because the iframe lives inside the player's Shadow DOM. Timeline seek, play, pause, and DOM inspection all silently no-op. **Always extract `iframeElement` first**, or use `resolveIframe` from `@hyperframes/studio` which handles both iframe and web-component hosts transparently.
+</Warning>
+
 ## Architecture
 
 The player uses an iframe inside a Shadow DOM container. This provides:
diff --git a/packages/player/README.md b/packages/player/README.md
index 1ef9c406f..0798d45e3 100644
--- a/packages/player/README.md
+++ b/packages/player/README.md
@@ -76,8 +76,63 @@ player.ready; // boolean (read-only)
 player.playbackRate; // number (read/write)
 player.muted; // boolean (read/write)
 player.loop; // boolean (read/write)
+
+// Inner iframe access (for advanced consumers — see "Advanced: iframe access" below)
+player.iframeElement; // HTMLIFrameElement (read-only)
 ```
 
+## Advanced: iframe access
+
+The composition runs inside a sandboxed `<iframe>` in the player's Shadow DOM. For most use cases you don't need direct access — the JavaScript API above is enough. But if you're building an editor, recorder, or custom timeline that needs to inspect the composition's DOM or read its `__player` / `__timelines` runtime objects, use the `iframeElement` getter:
+
+```js
+const player = document.querySelector("hyperframes-player");
+const iframe = player.iframeElement;
+
+// Now you can reach into the composition's DOM and runtime
+iframe.contentDocument.querySelectorAll("[data-composition-id]");
+iframe.contentWindow.__timelines;
+```
+
+This is the canonical way to bridge the player into tools like [`@hyperframes/studio`](../studio). The studio exports a `resolveIframe` helper that works with both iframe refs and web-component refs:
+
+```ts
+import { useTimelinePlayer, resolveIframe } from "@hyperframes/studio";
+
+const { iframeRef } = useTimelinePlayer();
+const player = document.createElement("hyperframes-player");
+player.setAttribute("src", src);
+container.appendChild(player);
+
+// Forward the inner iframe so useTimelinePlayer can drive play/pause/seek.
+iframeRef.current = resolveIframe(player);
+```
+
+### React: declarative ref pattern
+
+If you prefer JSX over imperative element creation, attach a ref directly to the web component and resolve the iframe inside an effect:
+
+```tsx
+import "@hyperframes/player";
+import type { HyperframesPlayer } from "@hyperframes/player";
+import { useTimelinePlayer, resolveIframe } from "@hyperframes/studio";
+
+function StudioPreview({ src }: { src: string }) {
+  const { iframeRef, onIframeLoad } = useTimelinePlayer();
+  const playerRef = useRef<HyperframesPlayer>(null);
+
+  useEffect(() => {
+    iframeRef.current = resolveIframe(playerRef.current);
+  });
+
+  return <hyperframes-player ref={playerRef} src={src} onLoad={onIframeLoad} />;
+}
+```
+
+> **Heads up — common gotcha**
+>
+> If you pass the `<hyperframes-player>` element itself (not `iframeElement`) into a hook that expects an `<iframe>`, every `.contentWindow` / `.contentDocument` access returns `null` because the iframe lives inside the player's Shadow DOM. Always extract `iframeElement` first, or use `resolveIframe` from `@hyperframes/studio` which handles both iframe and web-component hosts transparently.
+
 ## Events
 
 | Event        | Detail            | Fired when                                 |
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index 51a2a985a..53b5e5496 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -120,7 +120,27 @@ class HyperframesPlayer extends HTMLElement {
 
   // ── Public API ──
 
-  /** Access the inner iframe element (for advanced consumers like the studio). */
+  /**
+   * Access the inner `<iframe>` element rendering the composition.
+   *
+   * Use this when integrating the player with editors, recorders, or
+   * timeline tools (e.g. `@hyperframes/studio`) that need to inspect
+   * the composition's DOM or read its `__player` / `__timelines`
+   * runtime objects.
+   *
+   * **Common pitfall:** the iframe lives inside the player's Shadow DOM.
+   * Passing the `<hyperframes-player>` element itself to code that expects
+   * an `<iframe>` will silently break — `.contentWindow` returns `null`.
+   * Always extract `iframeElement` first:
+   *
+   * ```ts
+   * // ❌ Wrong — element ref doesn't expose contentWindow
+   * iframeRef.current = playerRef.current;
+   *
+   * // ✓ Right — bridge the actual iframe
+   * iframeRef.current = playerRef.current.iframeElement;
+   * ```
+   */
   get iframeElement(): HTMLIFrameElement {
     return this.iframe;
   }
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index d788f6bba..b9a08e662 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -12,6 +12,7 @@ export {
   VideoThumbnail,
   CompositionThumbnail,
   useTimelinePlayer,
+  resolveIframe,
   usePlayerStore,
   liveTime,
   formatTime,
diff --git a/packages/studio/src/player/hooks/useTimelinePlayer.ts b/packages/studio/src/player/hooks/useTimelinePlayer.ts
index 44280b15d..a32f68081 100644
--- a/packages/studio/src/player/hooks/useTimelinePlayer.ts
+++ b/packages/studio/src/player/hooks/useTimelinePlayer.ts
@@ -186,8 +186,34 @@ function unmutePreviewMedia(iframe: HTMLIFrameElement | null): void {
   }
 }
 
+/**
+ * Resolve the underlying iframe from any host element. Supports:
+ * - Direct `<iframe>` element (most common — studio's own `Player.tsx`)
+ * - Custom elements (e.g. `<hyperframes-player>`) whose shadow DOM contains an iframe
+ * - Wrapper elements whose light DOM contains a descendant iframe
+ *
+ * Exported so web-component consumers can pre-resolve the iframe before
+ * assigning it to `iframeRef` returned by `useTimelinePlayer`. Returns `null`
+ * when the element has no associated iframe yet.
+ *
+ * @example
+ * ```tsx
+ * const { iframeRef } = useTimelinePlayer();
+ * const playerElRef = useRef<HyperframesPlayer>(null);
+ *
+ * useEffect(() => {
+ *   iframeRef.current = resolveIframe(playerElRef.current);
+ * }, [iframeRef]);
+ * ```
+ */
+export function resolveIframe(el: Element | null): HTMLIFrameElement | null {
+  if (!el) return null;
+  if (el instanceof HTMLIFrameElement) return el;
+  return el.shadowRoot?.querySelector("iframe") ?? el.querySelector("iframe") ?? null;
+}
+
 export function useTimelinePlayer() {
-  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const rafRef = useRef<number>(0);
   const probeIntervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
   const pendingSeekRef = useRef<number | null>(null);
@@ -200,7 +226,8 @@ export function useTimelinePlayer() {
 
   const getAdapter = useCallback((): PlaybackAdapter | null => {
     try {
-      const win = iframeRef.current?.contentWindow as IframeWindow | null;
+      const iframe = iframeRef.current;
+      const win = iframe?.contentWindow as IframeWindow | null;
       if (!win) return null;
 
       if (win.__player && typeof win.__player.play === "function") {
@@ -554,8 +581,9 @@ export function useTimelinePlayer() {
         setIsPlaying(false);
 
         try {
-          const doc = iframeRef.current?.contentDocument;
-          const iframeWin = iframeRef.current?.contentWindow as IframeWindow | null;
+          const iframe = iframeRef.current;
+          const doc = iframe?.contentDocument;
+          const iframeWin = iframe?.contentWindow as IframeWindow | null;
           if (doc && iframeWin) {
             normalizePreviewViewport(doc, iframeWin);
             autoHealMissingCompositionIds(doc);
@@ -591,7 +619,7 @@ export function useTimelinePlayer() {
               const rootId = rootComp.getAttribute("data-composition-id") || "composition";
               // Derive compositionSrc from the iframe URL for thumbnail rendering.
               // URL pattern: /api/projects/{id}/preview/comp/{path}
-              const iframeSrc = iframeRef.current?.src || "";
+              const iframeSrc = iframe?.src || "";
               const compPathMatch = iframeSrc.match(/\/preview\/comp\/(.+?)(?:\?|$)/);
               const compositionSrc = compPathMatch
                 ? decodeURIComponent(compPathMatch[1])
@@ -682,7 +710,8 @@ export function useTimelinePlayer() {
     const handleMessage = (e: MessageEvent) => {
       const data = e.data;
       // Only process messages from the main preview iframe — ignore MediaPanel/ClipThumbnail iframes
-      if (e.source && iframeRef.current && e.source !== iframeRef.current.contentWindow) {
+      const ourIframe = iframeRef.current;
+      if (e.source && ourIframe && e.source !== ourIframe.contentWindow) {
         return;
       }
       // Also handle the runtime's state message which includes timeline data
@@ -690,8 +719,7 @@ export function useTimelinePlayer() {
         // State message means the runtime is alive — check for elements
         try {
           if (usePlayerStore.getState().elements.length === 0) {
-            const iframe = iframeRef.current;
-            const iframeWin = iframe?.contentWindow as IframeWindow | null;
+            const iframeWin = ourIframe?.contentWindow as IframeWindow | null;
             const manifest = iframeWin?.__clipManifest;
             if (manifest && manifest.clips.length > 0) {
               processTimelineMessageRef.current(manifest);
@@ -717,8 +745,7 @@ export function useTimelinePlayer() {
         // If manifest produced 0 elements after filtering, try DOM fallback
         if (usePlayerStore.getState().elements.length === 0) {
           try {
-            const iframe = iframeRef.current;
-            const doc = iframe?.contentDocument;
+            const doc = ourIframe?.contentDocument;
             const adapter = getAdapter();
             if (doc && adapter) {
               const els = parseTimelineFromDOM(doc, adapter.getDuration());
diff --git a/packages/studio/src/player/index.ts b/packages/studio/src/player/index.ts
index cea14c0ca..d8c516d98 100644
--- a/packages/studio/src/player/index.ts
+++ b/packages/studio/src/player/index.ts
@@ -6,7 +6,7 @@ export { VideoThumbnail } from "./components/VideoThumbnail";
 export { CompositionThumbnail } from "./components/CompositionThumbnail";
 
 // Hooks
-export { useTimelinePlayer } from "./hooks/useTimelinePlayer";
+export { useTimelinePlayer, resolveIframe } from "./hooks/useTimelinePlayer";
 
 // Store
 export { usePlayerStore, liveTime } from "./store/playerStore";