@osiris-smarttv/tv-viewport-frame 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OsirisTech SmartTV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @osiris-smarttv/tv-viewport-frame
+
+Fixed 1920x1080 viewport frame for Smart TV apps.
+
+This package keeps your app rendered inside a deterministic Full HD artboard while the host browser window can be any size. It handles center letterboxing, root `rem` scaling, and design-unit conversion so layout remains stable across TVs, emulator windows, and desktop testing.
+
+## Why this package
+
+- **Stable TV canvas:** one 1920x1080 design stage, centered in the host
+- **Responsive scale:** automatic scale-down for smaller host windows
+- **Design math helpers:** convert design px/rem into real rendered pixels
+- **Framework split:** pure `core` API + `react` integration layer
+- **DOM/CSS contract:** predictable stage/app attributes for integration and testing
+
+## Install
+
+```bash
+npm i @osiris-smarttv/tv-viewport-frame
+```
+
+## Exports
+
+- `@osiris-smarttv/tv-viewport-frame` (package root)
+- `@osiris-smarttv/tv-viewport-frame/core`
+- `@osiris-smarttv/tv-viewport-frame/react`
+- `@osiris-smarttv/tv-viewport-frame/styles.css`
+
+## Quick Start (React)
+
+```tsx
+import { TvViewportFrame } from '@osiris-smarttv/tv-viewport-frame/react'
+import '@osiris-smarttv/tv-viewport-frame/styles.css'
+
+export function AppRoot() {
+  return (
+    <TvViewportFrame>
+      <App />
+    </TvViewportFrame>
+  )
+}
+```
+
+### With config override
+
+```tsx
+<TvViewportFrame
+  config={{
+    fitToWindow: true,
+    showViewportBadge: false,
+  }}
+  onViewportChange={(snapshot) => {
+    // snapshot.scale, snapshot.host, snapshot.realSize
+  }}
+>
+  <App />
+</TvViewportFrame>
+```
+
+## Quick Start (Core only, no React)
+
+```ts
+import { createTvViewportSdk } from '@osiris-smarttv/tv-viewport-frame/core'
+
+const sdk = createTvViewportSdk()
+const snapshot = sdk.snapshot({ width: 1280, height: 720 })
+
+const scale = snapshot.scale
+const buttonPx = snapshot.realSize.px(96) // design 96px -> rendered px
+```
+
+## DOM and CSS contract
+
+When enabled, frame chrome renders:
+
+- root frame: `.tv-viewport-frame` (`data-tv-viewport-frame-root`)
+- stage: `.tv-viewport-frame__stage` (`data-tv-viewport-stage`)
+- app shell: `.tv-viewport-frame__app` (`data-tv-viewport-app`)
+
+The style export sets:
+
+- `html[data-tv-viewport-frame] { font-size: calc(var(--tv-viewport-scale, 1) * 100%); }`
+- stage dimensions via CSS vars (`--tv-viewport-stage-width-rem`, `--tv-viewport-stage-height-rem`)
+
+Import once in app bootstrap:
+
+```ts
+import '@osiris-smarttv/tv-viewport-frame/styles.css'
+```
+
+## React hooks
+
+From `@osiris-smarttv/tv-viewport-frame/react`:
+
+- `useTvViewport()` -> full viewport state (`enabled`, `snapshot`, `config`, `sdk`)
+- `useTvViewportScale()` -> current scale only
+- `useTvViewportRealSize()` -> px/rem conversion helpers bound to current scale
+- `useTvViewportSelector(selector, isEqual?)` -> optimized state selection
+
+## Core API highlights
+
+From `@osiris-smarttv/tv-viewport-frame/core`:
+
+- `createTvViewportSdk()`
+- `createTvViewportStore()`
+- `computeTvViewportScale()`
+- `designPxToRealPx()`, `designPxToRem()`, `designRemToRealPx()`
+- `applyTvViewportDocumentState()`, `clearTvViewportDocumentState()`
+- presets/constants: `TV_VIEWPORT_PRESETS`, `TV_VIEWPORT_FULL_HD`, `DEFAULT_TV_VIEWPORT_FRAME_CONFIG`
+
+## Runtime policy
+
+`TvViewportFrame` defaults to a runtime policy:
+
+- disabled in `test` mode
+- otherwise enabled unless `VITE_TV_VIEWPORT_FRAME=false`
+
+You can always override with explicit `enabled` prop.
+
+## Local development
+
+```bash
+yarn install
+yarn build
+yarn typecheck
+yarn test
+```
+
+## Manual publish (no GitHub Actions)
+
+```bash
+yarn publish:check
+yarn publish:dry-run
+yarn publish:manual
+```
+
+If publish returns `404` or permission errors for `@osiris-smarttv/*`, verify:
+
+- your npm account has publish access to scope `@osiris-smarttv`
+- package name is allowed by org policy
+- you are authenticated against `https://registry.npmjs.org/`

package/dist/core.d.ts

@@ -0,0 +1,67 @@
+import { d as TvViewportFrameConfig, g as TvViewportSdk, C as CreateTvViewportRealSizeOptions, f as TvViewportRealSizeContext, T as TvDesignPx, a as TvDesignSize, c as TvRealSize, R as ResolveTvViewportRealSizeOptions, h as TvViewportSize, e as TvViewportPreset, b as TvHostSize } from './viewportStore-yf19qOVB.js';
+export { i as TvViewportSnapshot, j as TvViewportStore, k as TvViewportStoreOptions, l as TvViewportStoreState, m as createTvViewportStore } from './viewportStore-yf19qOVB.js';
+
+declare function tvViewportConfigPartialEqual(a?: Partial<TvViewportFrameConfig>, b?: Partial<TvViewportFrameConfig>): boolean;
+
+declare function createTvViewportSdk(configInput?: Partial<TvViewportFrameConfig>): TvViewportSdk;
+
+declare function designPxToRem(designPx: TvDesignPx, remBasePx?: number): number;
+declare function designPxToRealPx(designPx: TvDesignPx, scale: number): number;
+declare function designRemToRealPx(designRem: number, rootFontSizePx: number): number;
+declare function designSizeToRealSize(design: TvDesignSize, scale: number): TvRealSize;
+declare function createTvViewportRealSize({ scale, uaRootPx, }: CreateTvViewportRealSizeOptions): TvViewportRealSizeContext;
+declare function resolveDesignPxToRealPx(designPx: TvDesignPx, hostWidth: number, hostHeight: number, options?: ResolveTvViewportRealSizeOptions): number;
+declare function resolveTvViewportRealSizeFromHost(hostWidth: number, hostHeight: number, options?: ResolveTvViewportRealSizeOptions): TvViewportRealSizeContext;
+declare function readTvViewportRealSizeFromDocument(uaRootPx?: number, root?: HTMLElement): TvViewportRealSizeContext;
+
+declare const TvViewportDomAttr: {
+    readonly Frame: "data-tv-viewport-frame";
+    readonly Root: "data-tv-viewport-frame-root";
+    readonly Stage: "data-tv-viewport-stage";
+    readonly App: "data-tv-viewport-app";
+};
+declare const TvViewportCssVar: {
+    readonly Width: "--tv-viewport-width";
+    readonly Height: "--tv-viewport-height";
+    readonly Scale: "--tv-viewport-scale";
+    readonly StageWidthRem: "--tv-viewport-stage-width-rem";
+    readonly StageHeightRem: "--tv-viewport-stage-height-rem";
+};
+type ApplyTvViewportDocumentStateInput = {
+    readonly config: TvViewportFrameConfig;
+    readonly scale: number;
+};
+declare function applyTvViewportDocumentState({ config, scale }: ApplyTvViewportDocumentStateInput, root?: HTMLElement): void;
+declare function clearTvViewportDocumentState(root?: HTMLElement): void;
+declare function readTvViewportScaleFromDocument(fallback?: number, root?: HTMLElement): number;
+
+declare const TV_VIEWPORT_REM_BASE_PX = 16;
+declare const TV_VIEWPORT_ROOT_FONT_PERCENT = 100;
+declare const TV_VIEWPORT_FULL_HD: TvViewportSize;
+/** Closed registry of supported TV design presets. */
+declare const TV_VIEWPORT_PRESETS: {
+    readonly "1920x1080": TvViewportSize;
+};
+declare function resolveTvViewportPreset(preset: TvViewportPreset): TvViewportSize;
+declare const TV_VIEWPORT_WIDTH_REM: number;
+declare const TV_VIEWPORT_HEIGHT_REM: number;
+declare const DEFAULT_TV_VIEWPORT_FRAME_CONFIG: TvViewportFrameConfig;
+declare function mergeTvViewportFrameConfig(partial?: Partial<TvViewportFrameConfig>): TvViewportFrameConfig;
+
+/** Sub-pixel tolerance when comparing viewport scale values. */
+declare const TV_VIEWPORT_SCALE_EPSILON = 0.000001;
+declare function tvViewportScalesEqual(a: number, b: number, epsilon?: number): boolean;
+/**
+ * Host scale relative to the TV design frame.
+ *
+ * `scale = min(hostW / frameW, hostH / frameH)` when `fitToWindow` (capped at 1).
+ */
+declare function computeTvViewportScale(host: TvHostSize, viewport?: TvViewportSize, fitToWindow?: boolean): number;
+declare function computeTvViewportScaleFromNumbers(hostWidth: number, hostHeight: number, viewport?: TvViewportSize, fitToWindow?: boolean): number;
+/** @deprecated Use {@link computeTvViewportScaleFromNumbers}. */
+declare const computeTvViewportRemScale: typeof computeTvViewportScaleFromNumbers;
+
+declare function resolveTvViewportRootFontSizePx(hostWidth: number, hostHeight: number, uaRootPx?: number, viewport?: TvViewportSize, fitToWindow?: boolean): number;
+declare function resolveTvViewportRootFontSizePercent(hostWidth: number, hostHeight: number, viewport?: TvViewportSize, fitToWindow?: boolean): number;
+
+export { CreateTvViewportRealSizeOptions, DEFAULT_TV_VIEWPORT_FRAME_CONFIG, ResolveTvViewportRealSizeOptions, TV_VIEWPORT_FULL_HD, TV_VIEWPORT_HEIGHT_REM, TV_VIEWPORT_PRESETS, TV_VIEWPORT_REM_BASE_PX, TV_VIEWPORT_ROOT_FONT_PERCENT, TV_VIEWPORT_SCALE_EPSILON, TV_VIEWPORT_WIDTH_REM, TvDesignPx, TvDesignSize, TvHostSize, TvRealSize, TvViewportCssVar, TvViewportDomAttr, TvViewportFrameConfig, TvViewportPreset, TvViewportRealSizeContext, TvViewportSdk, TvViewportSize, applyTvViewportDocumentState, clearTvViewportDocumentState, computeTvViewportRemScale, computeTvViewportScale, computeTvViewportScaleFromNumbers, createTvViewportRealSize, createTvViewportSdk, designPxToRealPx, designPxToRem, designRemToRealPx, designSizeToRealSize, mergeTvViewportFrameConfig, readTvViewportRealSizeFromDocument, readTvViewportScaleFromDocument, resolveDesignPxToRealPx, resolveTvViewportPreset, resolveTvViewportRealSizeFromHost, resolveTvViewportRootFontSizePercent, resolveTvViewportRootFontSizePx, tvViewportConfigPartialEqual, tvViewportScalesEqual };

package/dist/core.js

@@ -0,0 +1 @@
+function I(e,t){if(e===t)return  true;if(!e||!t)return !e&&!t;let r=e.viewport,o=t.viewport;return e.remBasePx===t.remBasePx&&e.fitToWindow===t.fitToWindow&&e.showViewportBadge===t.showViewportBadge&&r?.width===o?.width&&r?.height===o?.height&&r?.preset===o?.preset}var P={Frame:"data-tv-viewport-frame",Root:"data-tv-viewport-frame-root",Stage:"data-tv-viewport-stage",App:"data-tv-viewport-app"},p={Width:"--tv-viewport-width",Height:"--tv-viewport-height",Scale:"--tv-viewport-scale",StageWidthRem:"--tv-viewport-stage-width-rem",StageHeightRem:"--tv-viewport-stage-height-rem"},L=[p.Width,p.Height,p.Scale,p.StageWidthRem,p.StageHeightRem];function y({config:e,scale:t},r=document.documentElement){let{width:o,height:i,preset:s}=e.viewport;r.setAttribute(P.Frame,s),r.style.setProperty(p.Width,`${o}px`),r.style.setProperty(p.Height,`${i}px`),r.style.setProperty(p.Scale,String(t)),r.style.setProperty(p.StageWidthRem,`${e.viewport.width/e.remBasePx}rem`),r.style.setProperty(p.StageHeightRem,`${e.viewport.height/e.remBasePx}rem`);}function f(e=document.documentElement){e.removeAttribute(P.Frame);for(let t of L)e.style.removeProperty(t);}function w(e=1,t=document.documentElement){let r=t.style.getPropertyValue(p.Scale).trim();if(!r)return e;let o=Number.parseFloat(r);return Number.isFinite(o)?o:e}var d={FullHd:"1920x1080"};var T=16,S=100,a={width:1920,height:1080,preset:d.FullHd},_={[d.FullHd]:a};function M(e){return _[e]}var N=a.width/T,A=a.height/T,h={viewport:a,remBasePx:T,fitToWindow:true,showViewportBadge:false};function g(e){return {...h,...e,viewport:{...h.viewport,...e?.viewport}}}var F=1e-6;function z(e,t,r=F){return Math.abs(e-t)<r}function R(e,t=a,r=true){return m(e.width,e.height,t,r)}function m(e,t,r=a,o=true){return !o||e<=0||t<=0||e>=r.width&&t>=r.height?1:Math.min(e/r.width,t/r.height)}var B=m;function D(e,t=T){return e/t}function V(e,t){return e*t}function O(e,t){return e*t}function C(e,t){return {width:V(e.width,t),height:V(e.height,t)}}function v({scale:e,uaRootPx:t=T}){let r=t*e,o=S*e;return {scale:e,rootFontSizePercent:o,rootFontSizePx:r,px:i=>V(i,e),rem:i=>D(i,t),remPx:i=>O(i,r),size:i=>C(i,e)}}function U(e,t,r,o={}){let i=m(t,r,o.viewport,o.fitToWindow??true);return V(e,i)}function q(e,t,r={}){let o=m(e,t,r.viewport,r.fitToWindow??true);return v({scale:o,uaRootPx:r.uaRootPx})}function G(e=T,t=document.documentElement){return v({scale:w(1,t),uaRootPx:e})}function X(e){let t=g(e);return {config:t,computeScale:o=>R(o,t.viewport,t.fitToWindow),snapshot:o=>{let i=R(o,t.viewport,t.fitToWindow);return {scale:i,host:o,realSize:v({scale:i,uaRootPx:t.remBasePx})}},createRealSize:o=>v({scale:o,uaRootPx:t.remBasePx}),applyDocumentState:(o,i)=>y({config:t,scale:o},i),clearDocumentState:o=>f(o),readScaleFromDocument:(o,i)=>w(o,i),readRealSizeFromDocument:o=>v({scale:w(1,o),uaRootPx:t.remBasePx})}}var $={width:1920,height:1080};function H(e,t,r){return r?e.snapshot(t):e.snapshot($)}function k(e,t,r={}){let o=r.enabled??true,i=t,s=H(e,i,o),x={enabled:o,snapshot:s},c=new Set;o&&e.applyDocumentState(s.scale);let b=(n,l)=>{s=n,o=l,x={enabled:o,snapshot:s},c.forEach(u=>u()),r.onViewportChange?.(n);},W=n=>{o?e.applyDocumentState(n):e.clearDocumentState();};return {sdk:e,getState:()=>x,getServerState:()=>x,subscribe:n=>(c.add(n),()=>c.delete(n)),setEnabled:n=>{if(o===n)return;let l=H(e,i,n);n?e.applyDocumentState(l.scale):e.clearDocumentState(),b(l,n);},setHost:n=>{if(!o)return;let l=i.width===n.width&&i.height===n.height,u=e.snapshot(n),E=z(s.scale,u.scale);i=n,!(l&&E)&&(E||(W(u.scale),b(u,o)));},dispose:()=>{c.clear(),e.clearDocumentState();}}}function K(e,t,r=T,o=a,i=true){return r*m(e,t,o,i)}function Y(e,t,r=a,o=true){return S*m(e,t,r,o)}export{h as DEFAULT_TV_VIEWPORT_FRAME_CONFIG,a as TV_VIEWPORT_FULL_HD,A as TV_VIEWPORT_HEIGHT_REM,_ as TV_VIEWPORT_PRESETS,T as TV_VIEWPORT_REM_BASE_PX,S as TV_VIEWPORT_ROOT_FONT_PERCENT,F as TV_VIEWPORT_SCALE_EPSILON,N as TV_VIEWPORT_WIDTH_REM,p as TvViewportCssVar,P as TvViewportDomAttr,d as TvViewportPreset,y as applyTvViewportDocumentState,f as clearTvViewportDocumentState,B as computeTvViewportRemScale,R as computeTvViewportScale,m as computeTvViewportScaleFromNumbers,v as createTvViewportRealSize,X as createTvViewportSdk,k as createTvViewportStore,V as designPxToRealPx,D as designPxToRem,O as designRemToRealPx,C as designSizeToRealSize,g as mergeTvViewportFrameConfig,G as readTvViewportRealSizeFromDocument,w as readTvViewportScaleFromDocument,U as resolveDesignPxToRealPx,M as resolveTvViewportPreset,q as resolveTvViewportRealSizeFromHost,Y as resolveTvViewportRootFontSizePercent,K as resolveTvViewportRootFontSizePx,I as tvViewportConfigPartialEqual,z as tvViewportScalesEqual};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_TV_VIEWPORT_FRAME_CONFIG, TV_VIEWPORT_FULL_HD, TV_VIEWPORT_HEIGHT_REM, TV_VIEWPORT_PRESETS, TV_VIEWPORT_REM_BASE_PX, TV_VIEWPORT_ROOT_FONT_PERCENT, TV_VIEWPORT_SCALE_EPSILON, TV_VIEWPORT_WIDTH_REM, TvViewportCssVar, TvViewportDomAttr, applyTvViewportDocumentState, clearTvViewportDocumentState, computeTvViewportRemScale, computeTvViewportScale, computeTvViewportScaleFromNumbers, createTvViewportRealSize, createTvViewportSdk, designPxToRealPx, designPxToRem, designRemToRealPx, designSizeToRealSize, mergeTvViewportFrameConfig, readTvViewportRealSizeFromDocument, readTvViewportScaleFromDocument, resolveDesignPxToRealPx, resolveTvViewportPreset, resolveTvViewportRealSizeFromHost, resolveTvViewportRootFontSizePercent, resolveTvViewportRootFontSizePx, tvViewportConfigPartialEqual, tvViewportScalesEqual } from './core.js';
+export { C as CreateTvViewportRealSizeOptions, R as ResolveTvViewportRealSizeOptions, T as TvDesignPx, a as TvDesignSize, b as TvHostSize, c as TvRealSize, d as TvViewportFrameConfig, e as TvViewportPreset, f as TvViewportRealSizeContext, g as TvViewportSdk, h as TvViewportSize, i as TvViewportSnapshot, j as TvViewportStore, k as TvViewportStoreOptions, l as TvViewportStoreState, m as createTvViewportStore } from './viewportStore-yf19qOVB.js';
+export { TvViewportFrame, TvViewportHookValue, TvViewportProvider, TvViewportRuntimePolicy, TvViewportRuntimePolicyInput, computeViewportFrameScale, isTvViewportFrameEnabled, resolveTvViewportRuntimePolicy, useTvViewport, useTvViewportContext, useTvViewportContextOptional, useTvViewportRealSize, useTvViewportScale, useTvViewportSelector, useViewportFrameScale } from './react.js';
+import 'react';

package/dist/index.js

@@ -0,0 +1 @@
+import {createContext,memo,useRef,useSyncExternalStore,useContext,useMemo,useLayoutEffect,useState}from'react';import {jsx,jsxs}from'react/jsx-runtime';function W(e,t){if(e===t)return  true;if(!e||!t)return !e&&!t;let o=e.viewport,r=t.viewport;return e.remBasePx===t.remBasePx&&e.fitToWindow===t.fitToWindow&&e.showViewportBadge===t.showViewportBadge&&o?.width===r?.width&&o?.height===r?.height&&o?.preset===r?.preset}var I={Frame:"data-tv-viewport-frame",Root:"data-tv-viewport-frame-root",Stage:"data-tv-viewport-stage",App:"data-tv-viewport-app"},v={Width:"--tv-viewport-width",Height:"--tv-viewport-height",Scale:"--tv-viewport-scale",StageWidthRem:"--tv-viewport-stage-width-rem",StageHeightRem:"--tv-viewport-stage-height-rem"},ie=[v.Width,v.Height,v.Scale,v.StageWidthRem,v.StageHeightRem];function N({config:e,scale:t},o=document.documentElement){let{width:r,height:i,preset:n}=e.viewport;o.setAttribute(I.Frame,n),o.style.setProperty(v.Width,`${r}px`),o.style.setProperty(v.Height,`${i}px`),o.style.setProperty(v.Scale,String(t)),o.style.setProperty(v.StageWidthRem,`${e.viewport.width/e.remBasePx}rem`),o.style.setProperty(v.StageHeightRem,`${e.viewport.height/e.remBasePx}rem`);}function L(e=document.documentElement){e.removeAttribute(I.Frame);for(let t of ie)e.style.removeProperty(t);}function f(e=1,t=document.documentElement){let o=t.style.getPropertyValue(v.Scale).trim();if(!o)return e;let r=Number.parseFloat(o);return Number.isFinite(r)?r:e}var P={FullHd:"1920x1080"};var c=16,y=100,T={width:1920,height:1080,preset:P.FullHd},X={[P.FullHd]:T};function ne(e){return X[e]}var pe=T.width/c,ae=T.height/c,V={viewport:T,remBasePx:c,fitToWindow:true,showViewportBadge:false};function g(e){return {...V,...e,viewport:{...V.viewport,...e?.viewport}}}var K=1e-6;function h(e,t,o=K){return Math.abs(e-t)<o}function b(e,t=T,o=true){return u(e.width,e.height,t,o)}function u(e,t,o=T,r=true){return !r||e<=0||t<=0||e>=o.width&&t>=o.height?1:Math.min(e/o.width,t/o.height)}var se=u;function j(e,t=c){return e/t}function R(e,t){return e*t}function Y(e,t){return e*t}function J(e,t){return {width:R(e.width,t),height:R(e.height,t)}}function w({scale:e,uaRootPx:t=c}){let o=t*e,r=y*e;return {scale:e,rootFontSizePercent:r,rootFontSizePx:o,px:i=>R(i,e),rem:i=>j(i,t),remPx:i=>Y(i,o),size:i=>J(i,e)}}function me(e,t,o,r={}){let i=u(t,o,r.viewport,r.fitToWindow??true);return R(e,i)}function ve(e,t,o={}){let r=u(e,t,o.viewport,o.fitToWindow??true);return w({scale:r,uaRootPx:o.uaRootPx})}function ue(e=c,t=document.documentElement){return w({scale:f(1,t),uaRootPx:e})}function M(e){let t=g(e);return {config:t,computeScale:r=>b(r,t.viewport,t.fitToWindow),snapshot:r=>{let i=b(r,t.viewport,t.fitToWindow);return {scale:i,host:r,realSize:w({scale:i,uaRootPx:t.remBasePx})}},createRealSize:r=>w({scale:r,uaRootPx:t.remBasePx}),applyDocumentState:(r,i)=>N({config:t,scale:r},i),clearDocumentState:r=>L(r),readScaleFromDocument:(r,i)=>f(r,i),readRealSizeFromDocument:r=>w({scale:f(1,r),uaRootPx:t.remBasePx})}}var le={width:1920,height:1080};function Q(e,t,o){return o?e.snapshot(t):e.snapshot(le)}function k(e,t,o={}){let r=o.enabled??true,i=t,n=Q(e,i,r),m={enabled:r,snapshot:n},s=new Set;r&&e.applyDocumentState(n.scale);let a=(p,d)=>{n=p,r=d,m={enabled:r,snapshot:n},s.forEach(x=>x()),o.onViewportChange?.(p);},l=p=>{r?e.applyDocumentState(p):e.clearDocumentState();};return {sdk:e,getState:()=>m,getServerState:()=>m,subscribe:p=>(s.add(p),()=>s.delete(p)),setEnabled:p=>{if(r===p)return;let d=Q(e,i,p);p?e.applyDocumentState(d.scale):e.clearDocumentState(),a(d,p);},setHost:p=>{if(!r)return;let d=i.width===p.width&&i.height===p.height,x=e.snapshot(p),G=h(n.scale,x.scale);i=p,!(d&&G)&&(G||(l(x.scale),a(x,r)));},dispose:()=>{s.clear(),e.clearDocumentState();}}}function Te(e,t,o=c,r=T,i=true){return o*u(e,t,r,i)}function ce(e,t,o=T,r=true){return y*u(e,t,o,r)}function E(e,t){return t?`${e} ${t}`:e}function S(e={}){let t=e.mode??(typeof import.meta<"u"?import.meta.env?.MODE:void 0),o=e.frameFlag??(typeof import.meta<"u"?import.meta.env?.VITE_TV_VIEWPORT_FRAME:void 0);return t==="test"?{frameEnabled:false}:{frameEnabled:o!=="false"&&o!==false}}function we(){return S().frameEnabled}function Ve(){return typeof window>"u"?{width:0,height:0}:{width:window.innerWidth,height:window.innerHeight}}function z(e){if(typeof window>"u")return ()=>{};let t=0,o=false,r=()=>{o=false,e(Ve());},i=()=>{o||(o=true,t=window.requestAnimationFrame(r));};i(),window.addEventListener("resize",i);let n=typeof ResizeObserver<"u"?new ResizeObserver(i):null;return n&&document.documentElement&&n.observe(document.documentElement),()=>{window.removeEventListener("resize",i),t&&window.cancelAnimationFrame(t),n?.disconnect();}}var F=createContext(null);function _(){let e=useContext(F);if(!e)throw new Error("useTvViewport must be used within TvViewportProvider / TvViewportFrame");return e}function C(){return useContext(F)}function ee(e){let t=useRef(e);return W(t.current,e)||(t.current=e),t.current}function B({children:e,config:t,enabled:o=true,onViewportChange:r}){let i=ee(t),n=useMemo(()=>g(i),[i]),m=useMemo(()=>M(n),[n]),s=useRef(r);s.current=r;let a=useMemo(()=>k(m,typeof window>"u"?{width:1920,height:1080}:{width:window.innerWidth,height:window.innerHeight},{enabled:o,onViewportChange:p=>s.current?.(p)}),[m]);useLayoutEffect(()=>{a.setEnabled(o);},[o,a]),useLayoutEffect(()=>{if(o)return z(p=>{a.setHost(p);})},[o,a]),useLayoutEffect(()=>()=>a.dispose(),[a]);let l=useMemo(()=>({store:a,sdk:m}),[a,m]);return jsx(F.Provider,{value:l,children:e})}function U({viewport:e,fitToWindow:t,enabled:o}){let[r,i]=useState(1),n=useRef(r);return useLayoutEffect(()=>{if(!o){n.current=1,i(1);return}let m=(s,a)=>{let l=u(s,a,e,t);h(n.current,l)||(n.current=l,i(l));};return z(({width:s,height:a})=>m(s,a))},[o,t,e.height,e.width,e.preset]),r}function Re(e,t,o,r){return u(e,t,o,r)}var be=()=>()=>{};function D(e){let t=e.getState();return {sdk:e.sdk,config:e.sdk.config,enabled:t.enabled,snapshot:t.snapshot}}function Ee(e,t=Object.is){let{store:o}=_(),r=useRef(void 0);return useSyncExternalStore(o.subscribe,()=>{let i=e(D(o));return r.current!==void 0&&t(r.current,i)?r.current:(r.current=i,i)},()=>e(D(o)))}function $(){let{store:e}=_(),t=useRef(void 0);return useSyncExternalStore(e.subscribe,()=>{let o=D(e),r=t.current;return r&&r.enabled===o.enabled&&r.snapshot===o.snapshot&&r.sdk===o.sdk?r:(t.current=o,o)},()=>D(e))}function oe(){let e=C(),t=useSyncExternalStore(e?e.store.subscribe:be,()=>e?e.store.getState().snapshot.scale:1,()=>1),o=S().frameEnabled,r=U({enabled:!e&&o,fitToWindow:V.fitToWindow,viewport:V.viewport});return e?t:r}function ze(){let e=C(),t=oe(),o=e?.sdk.config.remBasePx??V.remBasePx;return useMemo(()=>w({scale:t,uaRootPx:o}),[o,t])}var Ce=memo(function({children:t,className:o,stageClassName:r,appClassName:i}){let{config:n,enabled:m,snapshot:s}=$();if(!m)return t;let{preset:a}=n.viewport,l=s.scale<1?` \xB7 ${Math.round(s.scale*100)}%`:"";return jsx("div",{className:E("tv-viewport-frame",o),"data-tv-viewport-frame-root":true,children:jsxs("div",{className:E("tv-viewport-frame__stage",r),"data-tv-viewport-stage":true,children:[n.showViewportBadge?jsxs("div",{className:"tv-viewport-frame__badge","aria-hidden":true,children:[a,l]}):null,jsx("div",{className:E("tv-viewport-frame__app",i),"data-tv-viewport-app":true,children:t})]})})});function Oe({children:e,config:t,enabled:o,onViewportChange:r,className:i,stageClassName:n,appClassName:m}){let s=o??S().frameEnabled,a=useRef(r);return a.current=r,jsx(B,{config:t,enabled:s,onViewportChange:l=>a.current?.(l),children:jsx(Ce,{className:i,stageClassName:n,appClassName:m,children:e})})}export{V as DEFAULT_TV_VIEWPORT_FRAME_CONFIG,T as TV_VIEWPORT_FULL_HD,ae as TV_VIEWPORT_HEIGHT_REM,X as TV_VIEWPORT_PRESETS,c as TV_VIEWPORT_REM_BASE_PX,y as TV_VIEWPORT_ROOT_FONT_PERCENT,K as TV_VIEWPORT_SCALE_EPSILON,pe as TV_VIEWPORT_WIDTH_REM,v as TvViewportCssVar,I as TvViewportDomAttr,Oe as TvViewportFrame,P as TvViewportPreset,B as TvViewportProvider,N as applyTvViewportDocumentState,L as clearTvViewportDocumentState,se as computeTvViewportRemScale,b as computeTvViewportScale,u as computeTvViewportScaleFromNumbers,Re as computeViewportFrameScale,w as createTvViewportRealSize,M as createTvViewportSdk,k as createTvViewportStore,R as designPxToRealPx,j as designPxToRem,Y as designRemToRealPx,J as designSizeToRealSize,we as isTvViewportFrameEnabled,g as mergeTvViewportFrameConfig,ue as readTvViewportRealSizeFromDocument,f as readTvViewportScaleFromDocument,me as resolveDesignPxToRealPx,ne as resolveTvViewportPreset,ve as resolveTvViewportRealSizeFromHost,ce as resolveTvViewportRootFontSizePercent,Te as resolveTvViewportRootFontSizePx,S as resolveTvViewportRuntimePolicy,W as tvViewportConfigPartialEqual,h as tvViewportScalesEqual,$ as useTvViewport,_ as useTvViewportContext,C as useTvViewportContextOptional,ze as useTvViewportRealSize,oe as useTvViewportScale,Ee as useTvViewportSelector,U as useViewportFrameScale};

package/dist/react.d.ts

@@ -0,0 +1,70 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { d as TvViewportFrameConfig, i as TvViewportSnapshot, j as TvViewportStore, g as TvViewportSdk, f as TvViewportRealSizeContext, h as TvViewportSize } from './viewportStore-yf19qOVB.js';
+
+type Props$1 = {
+    children: ReactNode;
+    config?: Partial<TvViewportFrameConfig>;
+    enabled?: boolean;
+    onViewportChange?: (snapshot: TvViewportSnapshot) => void;
+    className?: string;
+    stageClassName?: string;
+    appClassName?: string;
+};
+/**
+ * Runtime TV shell: 1920×1080 stage, centered letterbox, root `rem` scaling.
+ * Composes {@link TvViewportProvider} + chrome view.
+ */
+declare function TvViewportFrame({ children, config, enabled, onViewportChange, className, stageClassName, appClassName, }: Props$1): react.JSX.Element;
+
+type Props = {
+    children: ReactNode;
+    config?: Partial<TvViewportFrameConfig>;
+    enabled?: boolean;
+    onViewportChange?: (snapshot: TvViewportSnapshot) => void;
+};
+declare function TvViewportProvider({ children, config: configOverride, enabled, onViewportChange, }: Props): react.JSX.Element;
+
+type TvViewportContextValue = {
+    readonly store: TvViewportStore;
+    readonly sdk: TvViewportSdk;
+};
+declare function useTvViewportContext(): TvViewportContextValue;
+declare function useTvViewportContextOptional(): TvViewportContextValue | null;
+
+type TvViewportHookValue = {
+    readonly sdk: ReturnType<typeof useTvViewportContext>['sdk'];
+    readonly config: ReturnType<typeof useTvViewportContext>['sdk']['config'];
+    readonly enabled: boolean;
+    readonly snapshot: TvViewportSnapshot;
+};
+declare function useTvViewportSelector<T>(selector: (state: TvViewportHookValue) => T, isEqual?: (a: T, b: T) => boolean): T;
+declare function useTvViewport(): TvViewportHookValue;
+declare function useTvViewportScale(): number;
+declare function useTvViewportRealSize(): TvViewportRealSizeContext;
+
+type Options = {
+    viewport: TvViewportSize;
+    fitToWindow: boolean;
+    enabled: boolean;
+};
+declare function useViewportFrameScale({ viewport, fitToWindow, enabled }: Options): number;
+/** @deprecated Use {@link computeTvViewportScaleFromNumbers} via core. */
+declare function computeViewportFrameScale(windowWidth: number, windowHeight: number, viewport: TvViewportSize, fitToWindow: boolean): number;
+
+type TvViewportRuntimePolicy = {
+    readonly frameEnabled: boolean;
+};
+type TvViewportRuntimePolicyInput = {
+    readonly mode?: string;
+    readonly frameFlag?: string | boolean;
+};
+/**
+ * Default Vite policy — apps may override `enabled` on `TvViewportFrame` directly.
+ * Core SDK has zero `import.meta` coupling.
+ */
+declare function resolveTvViewportRuntimePolicy(input?: TvViewportRuntimePolicyInput): TvViewportRuntimePolicy;
+/** @deprecated Use {@link resolveTvViewportRuntimePolicy}. */
+declare function isTvViewportFrameEnabled(): boolean;
+
+export { TvViewportFrame, type TvViewportHookValue, TvViewportProvider, type TvViewportRuntimePolicy, type TvViewportRuntimePolicyInput, computeViewportFrameScale, isTvViewportFrameEnabled, resolveTvViewportRuntimePolicy, useTvViewport, useTvViewportContext, useTvViewportContextOptional, useTvViewportRealSize, useTvViewportScale, useTvViewportSelector, useViewportFrameScale };

package/dist/react.js

@@ -0,0 +1 @@
+import {createContext,memo,useRef,useSyncExternalStore,useContext,useMemo,useLayoutEffect,useState}from'react';import {jsx,jsxs}from'react/jsx-runtime';function S(e,t){return t?`${e} ${t}`:e}function w(e={}){let t=e.mode??(typeof import.meta<"u"?import.meta.env?.MODE:void 0),o=e.frameFlag??(typeof import.meta<"u"?import.meta.env?.VITE_TV_VIEWPORT_FRAME:void 0);return t==="test"?{frameEnabled:false}:{frameEnabled:o!=="false"&&o!==false}}function Z(){return w().frameEnabled}var M={Frame:"data-tv-viewport-frame"},l={Width:"--tv-viewport-width",Height:"--tv-viewport-height",Scale:"--tv-viewport-scale",StageWidthRem:"--tv-viewport-stage-width-rem",StageHeightRem:"--tv-viewport-stage-height-rem"},ee=[l.Width,l.Height,l.Scale,l.StageWidthRem,l.StageHeightRem];function B({config:e,scale:t},o=document.documentElement){let{width:r,height:i,preset:n}=e.viewport;o.setAttribute(M.Frame,n),o.style.setProperty(l.Width,`${r}px`),o.style.setProperty(l.Height,`${i}px`),o.style.setProperty(l.Scale,String(t)),o.style.setProperty(l.StageWidthRem,`${e.viewport.width/e.remBasePx}rem`),o.style.setProperty(l.StageHeightRem,`${e.viewport.height/e.remBasePx}rem`);}function A(e=document.documentElement){e.removeAttribute(M.Frame);for(let t of ee)e.style.removeProperty(t);}function E(e=1,t=document.documentElement){let o=t.style.getPropertyValue(l.Scale).trim();if(!o)return e;let r=Number.parseFloat(o);return Number.isFinite(r)?r:e}var _={FullHd:"1920x1080"};var d=16,U=100,v={width:1920,height:1080,preset:_.FullHd};v.width/d;v.height/d;var T={viewport:v,remBasePx:d,fitToWindow:true,showViewportBadge:false};function h(e){return {...T,...e,viewport:{...T.viewport,...e?.viewport}}}var te=1e-6;function y(e,t,o=te){return Math.abs(e-t)<o}function H(e,t=v,o=true){return x(e.width,e.height,t,o)}function x(e,t,o=v,r=true){return !r||e<=0||t<=0||e>=o.width&&t>=o.height?1:Math.min(e/o.width,t/o.height)}function oe(e,t=d){return e/t}function D(e,t){return e*t}function re(e,t){return e*t}function ie(e,t){return {width:D(e.width,t),height:D(e.height,t)}}function V({scale:e,uaRootPx:t=d}){let o=t*e,r=U*e;return {scale:e,rootFontSizePercent:r,rootFontSizePx:o,px:i=>D(i,e),rem:i=>oe(i,t),remPx:i=>re(i,o),size:i=>ie(i,e)}}function $(e){let t=h(e);return {config:t,computeScale:r=>H(r,t.viewport,t.fitToWindow),snapshot:r=>{let i=H(r,t.viewport,t.fitToWindow);return {scale:i,host:r,realSize:V({scale:i,uaRootPx:t.remBasePx})}},createRealSize:r=>V({scale:r,uaRootPx:t.remBasePx}),applyDocumentState:(r,i)=>B({config:t,scale:r},i),clearDocumentState:r=>A(r),readScaleFromDocument:(r,i)=>E(r,i),readRealSizeFromDocument:r=>V({scale:E(1,r),uaRootPx:t.remBasePx})}}var ne={width:1920,height:1080};function q(e,t,o){return o?e.snapshot(t):e.snapshot(ne)}function G(e,t,o={}){let r=o.enabled??true,i=t,n=q(e,i,r),m={enabled:r,snapshot:n},s=new Set;r&&e.applyDocumentState(n.scale);let a=(p,c)=>{n=p,r=c,m={enabled:r,snapshot:n},s.forEach(f=>f()),o.onViewportChange?.(p);},u=p=>{r?e.applyDocumentState(p):e.clearDocumentState();};return {sdk:e,getState:()=>m,getServerState:()=>m,subscribe:p=>(s.add(p),()=>s.delete(p)),setEnabled:p=>{if(r===p)return;let c=q(e,i,p);p?e.applyDocumentState(c.scale):e.clearDocumentState(),a(c,p);},setHost:p=>{if(!r)return;let c=i.width===p.width&&i.height===p.height,f=e.snapshot(p),L=y(n.scale,f.scale);i=p,!(c&&L)&&(L||(u(f.scale),a(f,r)));},dispose:()=>{s.clear(),e.clearDocumentState();}}}function pe(){return typeof window>"u"?{width:0,height:0}:{width:window.innerWidth,height:window.innerHeight}}function g(e){if(typeof window>"u")return ()=>{};let t=0,o=false,r=()=>{o=false,e(pe());},i=()=>{o||(o=true,t=window.requestAnimationFrame(r));};i(),window.addEventListener("resize",i);let n=typeof ResizeObserver<"u"?new ResizeObserver(i):null;return n&&document.documentElement&&n.observe(document.documentElement),()=>{window.removeEventListener("resize",i),t&&window.cancelAnimationFrame(t),n?.disconnect();}}var b=createContext(null);function R(){let e=useContext(b);if(!e)throw new Error("useTvViewport must be used within TvViewportProvider / TvViewportFrame");return e}function P(){return useContext(b)}function X(e,t){if(e===t)return  true;if(!e||!t)return !e&&!t;let o=e.viewport,r=t.viewport;return e.remBasePx===t.remBasePx&&e.fitToWindow===t.fitToWindow&&e.showViewportBadge===t.showViewportBadge&&o?.width===r?.width&&o?.height===r?.height&&o?.preset===r?.preset}function j(e){let t=useRef(e);return X(t.current,e)||(t.current=e),t.current}function N({children:e,config:t,enabled:o=true,onViewportChange:r}){let i=j(t),n=useMemo(()=>h(i),[i]),m=useMemo(()=>$(n),[n]),s=useRef(r);s.current=r;let a=useMemo(()=>G(m,typeof window>"u"?{width:1920,height:1080}:{width:window.innerWidth,height:window.innerHeight},{enabled:o,onViewportChange:p=>s.current?.(p)}),[m]);useLayoutEffect(()=>{a.setEnabled(o);},[o,a]),useLayoutEffect(()=>{if(o)return g(p=>{a.setHost(p);})},[o,a]),useLayoutEffect(()=>()=>a.dispose(),[a]);let u=useMemo(()=>({store:a,sdk:m}),[a,m]);return jsx(b.Provider,{value:u,children:e})}function W({viewport:e,fitToWindow:t,enabled:o}){let[r,i]=useState(1),n=useRef(r);return useLayoutEffect(()=>{if(!o){n.current=1,i(1);return}let m=(s,a)=>{let u=x(s,a,e,t);y(n.current,u)||(n.current=u,i(u));};return g(({width:s,height:a})=>m(s,a))},[o,t,e.height,e.width,e.preset]),r}function we(e,t,o,r){return x(e,t,o,r)}var de=()=>()=>{};function C(e){let t=e.getState();return {sdk:e.sdk,config:e.sdk.config,enabled:t.enabled,snapshot:t.snapshot}}function Ve(e,t=Object.is){let{store:o}=R(),r=useRef(void 0);return useSyncExternalStore(o.subscribe,()=>{let i=e(C(o));return r.current!==void 0&&t(r.current,i)?r.current:(r.current=i,i)},()=>e(C(o)))}function k(){let{store:e}=R(),t=useRef(void 0);return useSyncExternalStore(e.subscribe,()=>{let o=C(e),r=t.current;return r&&r.enabled===o.enabled&&r.snapshot===o.snapshot&&r.sdk===o.sdk?r:(t.current=o,o)},()=>C(e))}function J(){let e=P(),t=useSyncExternalStore(e?e.store.subscribe:de,()=>e?e.store.getState().snapshot.scale:1,()=>1),o=w().frameEnabled,r=W({enabled:!e&&o,fitToWindow:T.fitToWindow,viewport:T.viewport});return e?t:r}function fe(){let e=P(),t=J(),o=e?.sdk.config.remBasePx??T.remBasePx;return useMemo(()=>V({scale:t,uaRootPx:o}),[o,t])}var ye=memo(function({children:t,className:o,stageClassName:r,appClassName:i}){let{config:n,enabled:m,snapshot:s}=k();if(!m)return t;let{preset:a}=n.viewport,u=s.scale<1?` \xB7 ${Math.round(s.scale*100)}%`:"";return jsx("div",{className:S("tv-viewport-frame",o),"data-tv-viewport-frame-root":true,children:jsxs("div",{className:S("tv-viewport-frame__stage",r),"data-tv-viewport-stage":true,children:[n.showViewportBadge?jsxs("div",{className:"tv-viewport-frame__badge","aria-hidden":true,children:[a,u]}):null,jsx("div",{className:S("tv-viewport-frame__app",i),"data-tv-viewport-app":true,children:t})]})})});function xe({children:e,config:t,enabled:o,onViewportChange:r,className:i,stageClassName:n,appClassName:m}){let s=o??w().frameEnabled,a=useRef(r);return a.current=r,jsx(N,{config:t,enabled:s,onViewportChange:u=>a.current?.(u),children:jsx(ye,{className:i,stageClassName:n,appClassName:m,children:e})})}export{xe as TvViewportFrame,N as TvViewportProvider,we as computeViewportFrameScale,Z as isTvViewportFrameEnabled,w as resolveTvViewportRuntimePolicy,k as useTvViewport,R as useTvViewportContext,P as useTvViewportContextOptional,fe as useTvViewportRealSize,J as useTvViewportScale,Ve as useTvViewportSelector,W as useViewportFrameScale};

package/dist/tv-viewport-frame.css

@@ -0,0 +1,52 @@
+/**
+ * Root rem + stage sizing for the TV frame.
+ * `html` font-size drives scale; stage uses rem so the canvas tracks root.
+ */
+html[data-tv-viewport-frame] {
+  font-size: calc(var(--tv-viewport-scale, 1) * 100%);
+}
+
+.tv-viewport-frame {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  background: #000;
+}
+
+.tv-viewport-frame__stage {
+  position: relative;
+  flex-shrink: 0;
+  overflow: hidden;
+  width: var(--tv-viewport-stage-width-rem, 120rem);
+  height: var(--tv-viewport-stage-height-rem, 67.5rem);
+  background: var(--tv-viewport-canvas, #0a0a0a);
+}
+
+.tv-viewport-frame__app {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.tv-viewport-frame__badge {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  z-index: 2147483646;
+  padding: 0.2rem 0.45rem;
+  border-radius: 0.25rem;
+  background: rgba(0, 0, 0, 0.72);
+  color: rgba(255, 255, 255, 0.72);
+  font-size: 0.6875rem;
+  line-height: 1.35;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  pointer-events: none;
+  user-select: none;
+}

package/dist/viewportStore-yf19qOVB.d.ts

@@ -0,0 +1,87 @@
+declare const TvViewportPreset: {
+    readonly FullHd: "1920x1080";
+};
+type TvViewportPreset = (typeof TvViewportPreset)[keyof typeof TvViewportPreset];
+type TvViewportSize = {
+    readonly width: number;
+    readonly height: number;
+    readonly preset: TvViewportPreset;
+};
+type TvViewportFrameConfig = {
+    readonly viewport: TvViewportSize;
+    /** Maps design px → rem for the stage (`1920 / remBasePx` → 120rem). */
+    readonly remBasePx: number;
+    /** Scale stage down when the host display is smaller than the frame. */
+    readonly fitToWindow: boolean;
+    /** Optional corner label (resolution / scale). */
+    readonly showViewportBadge: boolean;
+};
+/** Length in the 1920×1080 design coordinate system (1 unit = 1 CSS px at reference). */
+type TvDesignPx = number;
+type TvDesignSize = {
+    readonly width: TvDesignPx;
+    readonly height: TvDesignPx;
+};
+/** Rendered size in screen pixels after viewport-frame scale is applied. */
+type TvRealSize = {
+    readonly width: number;
+    readonly height: number;
+};
+type TvViewportRealSizeContext = {
+    readonly scale: number;
+    readonly rootFontSizePercent: number;
+    readonly rootFontSizePx: number;
+    px: (designPx: TvDesignPx) => number;
+    rem: (designPx: TvDesignPx) => number;
+    remPx: (designRem: number) => number;
+    size: (design: TvDesignSize) => TvRealSize;
+};
+type TvHostSize = {
+    readonly width: number;
+    readonly height: number;
+};
+type TvViewportSnapshot = {
+    readonly scale: number;
+    readonly host: TvHostSize;
+    readonly realSize: TvViewportRealSizeContext;
+};
+type CreateTvViewportRealSizeOptions = {
+    readonly scale: number;
+    readonly uaRootPx?: number;
+};
+type ResolveTvViewportRealSizeOptions = {
+    readonly viewport?: TvViewportSize;
+    readonly fitToWindow?: boolean;
+    readonly uaRootPx?: number;
+};
+type TvViewportSdk = {
+    readonly config: TvViewportFrameConfig;
+    computeScale: (host: TvHostSize) => number;
+    snapshot: (host: TvHostSize) => TvViewportSnapshot;
+    createRealSize: (scale: number) => TvViewportRealSizeContext;
+    applyDocumentState: (scale: number, root?: HTMLElement) => void;
+    clearDocumentState: (root?: HTMLElement) => void;
+    readScaleFromDocument: (fallback?: number, root?: HTMLElement) => number;
+    readRealSizeFromDocument: (root?: HTMLElement) => TvViewportRealSizeContext;
+};
+
+type TvViewportStoreState = {
+    readonly enabled: boolean;
+    readonly snapshot: TvViewportSnapshot;
+};
+type TvViewportStoreOptions = {
+    readonly enabled?: boolean;
+    readonly onViewportChange?: (snapshot: TvViewportSnapshot) => void;
+};
+type TvViewportStore = {
+    readonly sdk: TvViewportSdk;
+    getState: () => TvViewportStoreState;
+    getServerState: () => TvViewportStoreState;
+    subscribe: (listener: () => void) => () => void;
+    setEnabled: (enabled: boolean) => void;
+    setHost: (host: TvHostSize) => void;
+    dispose: () => void;
+};
+declare function createTvViewportStore(sdk: TvViewportSdk, initialHost: TvHostSize, options?: TvViewportStoreOptions): TvViewportStore;
+
+export { type CreateTvViewportRealSizeOptions as C, type ResolveTvViewportRealSizeOptions as R, type TvDesignPx as T, type TvDesignSize as a, type TvHostSize as b, type TvRealSize as c, type TvViewportFrameConfig as d, TvViewportPreset as e, type TvViewportRealSizeContext as f, type TvViewportSdk as g, type TvViewportSize as h, type TvViewportSnapshot as i, type TvViewportStore as j, type TvViewportStoreOptions as k, type TvViewportStoreState as l, createTvViewportStore as m };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@osiris-smarttv/tv-viewport-frame",
+  "version": "0.1.0",
+  "description": "Fixed 1920×1080 TV viewport shell — letterbox, root rem scaling, design-unit math",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OsirisTech-SmartTV/tv-viewport-frame.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OsirisTech-SmartTV/tv-viewport-frame/issues"
+  },
+  "homepage": "https://github.com/OsirisTech-SmartTV/tv-viewport-frame#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./styles.css": "./dist/tv-viewport-frame.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": false },
+    "react-dom": { "optional": false }
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.0.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tsup": "^8.5.0",
+    "typescript": "~6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "clean": "node scripts/clean.mjs",
+    "build": "yarn build:js && yarn build:styles",
+    "build:js": "tsup",
+    "build:styles": "node scripts/copy-styles.mjs",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "yarn typecheck && yarn test",
+    "publish:check": "yarn clean && yarn build && yarn verify && npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run --access public",
+    "publish:manual": "npm publish --access public",
+    "prepublishOnly": "yarn clean && yarn build && yarn verify"
+  }
+}