From 7fbb908e0374ac372bffaea654a3efcc10c2f3a5 Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Thu, 23 Jul 2026 02:02:36 +0530
Subject: [PATCH] fix(ui): make the .kino root backdrop a themeable --kino-bg
 token

The root was hardcoded background: black, which flashes through before
the media/stage paints. Hosts embedding the player over a light surface
had no way to override it. Expose --kino-bg (default black, so existing
players are unchanged); consumers can set it via their stylesheet or the
theme prop.
---
 .changeset/themeable-root-bg.md | 8 ++++++++
 README.md                       | 1 +
 src/styles/kino.css             | 5 ++++-
 3 files changed, 13 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/themeable-root-bg.md

diff --git a/.changeset/themeable-root-bg.md b/.changeset/themeable-root-bg.md
new file mode 100644
index 0000000..98bd5e5
--- /dev/null
+++ b/.changeset/themeable-root-bg.md
@@ -0,0 +1,8 @@
+---
+"@karnstack/kino": patch
+---
+
+The `.kino` root backdrop is now a `--kino-bg` token (default `black`), so a
+host embedding the player over a light page can theme it (e.g. `--kino-bg:
+transparent`) instead of flashing black before the media paints. Default is
+unchanged, so existing players stay black.
diff --git a/README.md b/README.md
index 2f8a0b3..cfb2b07 100644
--- a/README.md
+++ b/README.md
@@ -298,6 +298,7 @@ For deeper control, every visual is driven by CSS custom properties on the `.kin
 | Custom property         | Default                                       | Role                                          |
 | ----------------------- | --------------------------------------------- | --------------------------------------------- |
 | `--kino-accent`         | `oklch(50.8% 0.118 165.612)`                  | Accent color (progress, active items, ranges) |
+| `--kino-bg`             | `black`                                       | Root backdrop behind the media/stage          |
 | `--kino-radius`         | `12px`                                        | Corner radius of glass surfaces               |
 | `--kino-surface`        | `color-mix(in oklab, black 55%, transparent)` | Glass surface fill                            |
 | `--kino-surface-strong` | `color-mix(in oklab, black 70%, transparent)` | Stronger surface (idle play button)           |
diff --git a/src/styles/kino.css b/src/styles/kino.css
index 60dcc37..753fd2b 100644
--- a/src/styles/kino.css
+++ b/src/styles/kino.css
@@ -1,6 +1,9 @@
 .kino {
   /* theme tokens (overridable via inline style or a theme prop) */
   --kino-accent: oklch(50.8% 0.118 165.612);
+  /* Root backdrop behind the media/stage. Black suits real video; a scenes
+     host over a light page can override it (e.g. --kino-bg: transparent). */
+  --kino-bg: black;
   --kino-radius: 12px;
   --kino-surface: color-mix(in oklab, black 55%, transparent);
   --kino-surface-strong: color-mix(in oklab, black 70%, transparent);
@@ -19,7 +22,7 @@
   height: 100%;
   color: var(--kino-text);
   font-family: ui-sans-serif, system-ui, sans-serif;
-  background: black;
+  background: var(--kino-bg);
   overflow: hidden;
   /* container queries so captions/flash scale with the player, not the page */
   container-type: inline-size;