@use-voltra/core 2.0.0 → 2.1.0

package/build/cjs/index.js

@@ -19,4 +19,5 @@ __exportStar(require("./payload.js"), exports);
 __exportStar(require("./payload/short-names.js"), exports);
 __exportStar(require("./renderer/index.js"), exports);
 __exportStar(require("./types.js"), exports);
+__exportStar(require("./widget-environment.js"), exports);
 //# sourceMappingURL=index.js.map

package/build/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iEAA8C;AAC9C,+CAA4B;AAC5B,2DAAwC;AACxC,sDAAmC;AACnC,6CAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iEAA8C;AAC9C,+CAA4B;AAC5B,2DAAwC;AACxC,sDAAmC;AACnC,6CAA0B;AAC1B,0DAAuC"}

package/build/cjs/widget-environment.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIosEnv = isIosEnv;
+exports.isAndroidEnv = isAndroidEnv;
+/**
+ * Type guard — returns true when the runtime env is an iOS-platform env.
+ *
+ * @example
+ *   if (isIosEnv(env)) {
+ *     // env.widgetRenderingMode is narrowed to the concrete value (not undefined)
+ *   }
+ */
+function isIosEnv(env) {
+    return env.widgetRenderingMode !== undefined;
+}
+/**
+ * Type guard — returns true when the runtime env is an Android-platform env.
+ *
+ * Android carries no platform-only runtime field (Material You colors are consumed via
+ * `AndroidDynamicColors` tokens resolved by the native renderer, not through `env`), so this is
+ * the complement of {@link isIosEnv}.
+ */
+function isAndroidEnv(env) {
+    return !isIosEnv(env);
+}
+//# sourceMappingURL=widget-environment.js.map

package/build/cjs/widget-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-environment.js","sourceRoot":"","sources":["../../src/widget-environment.ts"],"names":[],"mappings":";;AAkGA,4BAIC;AASD,oCAEC;AAvBD;;;;;;;GAOG;AACH,SAAgB,QAAQ,CACtB,GAAsB;IAEtB,OAAO,GAAG,CAAC,mBAAmB,KAAK,SAAS,CAAA;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,GAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;AACvB,CAAC"}

package/build/esm/index.js

@@ -3,4 +3,5 @@ export * from './payload.js';
 export * from './payload/short-names.js';
 export * from './renderer/index.js';
 export * from './types.js';
+export * from './widget-environment.js';
 //# sourceMappingURL=index.js.map

package/build/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA"}

package/build/esm/widget-environment.js

@@ -0,0 +1,22 @@
+/**
+ * Type guard — returns true when the runtime env is an iOS-platform env.
+ *
+ * @example
+ *   if (isIosEnv(env)) {
+ *     // env.widgetRenderingMode is narrowed to the concrete value (not undefined)
+ *   }
+ */
+export function isIosEnv(env) {
+    return env.widgetRenderingMode !== undefined;
+}
+/**
+ * Type guard — returns true when the runtime env is an Android-platform env.
+ *
+ * Android carries no platform-only runtime field (Material You colors are consumed via
+ * `AndroidDynamicColors` tokens resolved by the native renderer, not through `env`), so this is
+ * the complement of {@link isIosEnv}.
+ */
+export function isAndroidEnv(env) {
+    return !isIosEnv(env);
+}
+//# sourceMappingURL=widget-environment.js.map

package/build/esm/widget-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-environment.js","sourceRoot":"","sources":["../../src/widget-environment.ts"],"names":[],"mappings":"AA0FA;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CACtB,GAAsB;IAEtB,OAAO,GAAG,CAAC,mBAAmB,KAAK,SAAS,CAAA;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;AACvB,CAAC"}

package/build/types/index.d.ts

@@ -3,4 +3,5 @@ export * from './payload.js';
 export * from './payload/short-names.js';
 export * from './renderer/index.js';
 export * from './types.js';
+export * from './widget-environment.js';
 //# sourceMappingURL=index.d.ts.map

package/build/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,cAAc,CAAA;AAC5B,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA;AAC1B,cAAc,yBAAyB,CAAA"}

package/build/types/widget-environment.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Env shape consumed by Dynamic Widgets.
+ *
+ * Dynamic Widgets are functions of `(props, env) => JSX`, evaluated inside the
+ * Voltra JS runtime (JSC on iOS, Hermes on Android) at every render. The `env` second
+ * argument is populated by the native runtime at draw time and carries:
+ *
+ * - **Runtime device state** (`colorScheme`, `widgetFamily`, etc.) captured per render
+ * - **Platform-specific runtime state** (`widgetRenderingMode` on iOS), present only on the
+ *   platform that has the concept
+ * - **AppIntent / user-configured params** under `env.configuration` (TypeScript-typed per
+ *   widget via the generic parameter)
+ * - **Build env** under `env.build.*` — values that don't change between renders inside a
+ *   process (isDev, Metro URL, app version, Voltra version)
+ *
+ * The shape mirrors expo-widgets' `WidgetEnvironment` for the runtime device fields, with
+ * a Voltra-specific `env.build.*` namespace added for dev-mode tooling.
+ *
+ * @typeParam TConfig - Shape of `env.configuration` (AppIntent / user-configured params).
+ *   Defaults to `undefined` for widgets that don't accept user configuration. Widget authors
+ *   can supply a more specific type per widget for typed access.
+ */
+export type WidgetEnvironment<TConfig extends Record<string, unknown> | undefined = undefined> = {
+    /** Date the widget is being rendered for. Transported as epoch ms over the JS boundary
+     * and reconstructed as `Date` by the runtime entry. */
+    date: Date;
+    /** Widget size family. iOS values: `systemSmall`, `systemMedium`, `systemLarge`, etc.
+     * Android values: synthesized from Glance `LocalSize` (e.g. `"200x200"`). */
+    widgetFamily: string;
+    /** Current color scheme of the widget's environment. May be `undefined` if the platform
+     * doesn't expose it (rare). */
+    colorScheme?: 'light' | 'dark';
+    /** BCP-47 locale tag — for example `"en-US"` or `"pl-PL"`. */
+    locale?: string;
+    /** iOS — rendering mode the widget is being drawn in. `fullColor` on home screen,
+     * `accented` on tinted/Liquid Glass widgets (iOS 18+) and watchOS, `vibrant` on lock
+     * screen. Maps to SwiftUI `@Environment(\.widgetRenderingMode)`. */
+    widgetRenderingMode?: 'fullColor' | 'accented' | 'vibrant';
+    /** iOS — whether the system is drawing a container background behind the widget.
+     * Maps to SwiftUI `@Environment(\.showsWidgetContainerBackground)`. iOS 17+. */
+    showsWidgetContainerBackground?: boolean;
+    /** AppIntent / user-configured parameters for this widget. `undefined` for widgets that
+     * don't accept user configuration. Typed per widget via the [TConfig] generic. */
+    configuration: TConfig;
+    /** Build / process-level metadata, populated by the runtime once per process. Static for
+     * the JS runtime's lifetime; does not change between renders. */
+    build: WidgetBuildEnvironment;
+};
+/**
+ * Build / process metadata available inside the widget render function. Populated by the
+ * native runtime; identical across every render in a process.
+ */
+export type WidgetBuildEnvironment = {
+    /** True when running against a development build (DEBUG / `__DEV__`). Used to gate
+     * dev-mode behaviour like fetching bundles from Metro. */
+    isDev: boolean;
+    /** URL of the Metro dev server when `isDev` is true. Used by the runtime to fetch widget
+     * bundles for hot-reload. `undefined` in release builds. */
+    metroUrl?: string;
+    /** App version string (`CFBundleShortVersionString` on iOS, `versionName` on Android). */
+    appVersion: string;
+    /** Voltra package version (`@use-voltra/core`). Surfaces in error reports and lets
+     * widgets gate behaviour by compatibility level if needed. */
+    voltraVersion: string;
+};
+/**
+ * Type guard — returns true when the runtime env is an iOS-platform env.
+ *
+ * @example
+ *   if (isIosEnv(env)) {
+ *     // env.widgetRenderingMode is narrowed to the concrete value (not undefined)
+ *   }
+ */
+export declare function isIosEnv(env: WidgetEnvironment): env is WidgetEnvironment & {
+    widgetRenderingMode: NonNullable<WidgetEnvironment['widgetRenderingMode']>;
+};
+/**
+ * Type guard — returns true when the runtime env is an Android-platform env.
+ *
+ * Android carries no platform-only runtime field (Material You colors are consumed via
+ * `AndroidDynamicColors` tokens resolved by the native renderer, not through `env`), so this is
+ * the complement of {@link isIosEnv}.
+ */
+export declare function isAndroidEnv(env: WidgetEnvironment): boolean;
+//# sourceMappingURL=widget-environment.d.ts.map

package/build/types/widget-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-environment.d.ts","sourceRoot":"","sources":["../../src/widget-environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,IAAI;IAC/F;2DACuD;IACvD,IAAI,EAAE,IAAI,CAAA;IAEV;iFAC6E;IAC7E,YAAY,EAAE,MAAM,CAAA;IAEpB;mCAC+B;IAC/B,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAE9B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IAOf;;wEAEoE;IACpE,mBAAmB,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA;IAE1D;oFACgF;IAChF,8BAA8B,CAAC,EAAE,OAAO,CAAA;IAMxC;sFACkF;IAClF,aAAa,EAAE,OAAO,CAAA;IAMtB;qEACiE;IACjE,KAAK,EAAE,sBAAsB,CAAA;CAC9B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;8DAC0D;IAC1D,KAAK,EAAE,OAAO,CAAA;IAEd;gEAC4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAA;IAElB;kEAC8D;IAC9D,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,iBAAiB,GACrB,GAAG,IAAI,iBAAiB,GAAG;IAAE,mBAAmB,EAAE,WAAW,CAAC,iBAAiB,CAAC,qBAAqB,CAAC,CAAC,CAAA;CAAE,CAE3G;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAE5D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-voltra/core",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Generic renderer and payload utilities for Voltra",
   "main": "build/cjs/index.js",
   "module": "build/esm/index.js",
@@ -16,6 +16,7 @@
   },
   "files": [
     "build",
+    "src",
     "README.md"
   ],
   "dependencies": {

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './jsx/createVoltraComponent.js'
+export * from './payload.js'
+export * from './payload/short-names.js'
+export * from './renderer/index.js'
+export * from './types.js'
+export * from './widget-environment.js'

package/src/jsx/createVoltraComponent.ts

@@ -0,0 +1,36 @@
+import type { ComponentType } from 'react'
+import { createElement } from 'react'
+
+export const VOLTRA_COMPONENT_TAG = Symbol.for('VOLTRA_COMPONENT_TAG')
+
+export type VoltraComponent<TProps extends Record<string, unknown>> = ComponentType<TProps> & {
+  displayName: string
+  [VOLTRA_COMPONENT_TAG]: true
+}
+
+export type VoltraComponentOptions<TProps extends Record<string, unknown>> = {
+  toJSON?: (props: TProps) => Record<string, unknown>
+}
+
+export const createVoltraComponent = <TProps extends Record<string, unknown>>(
+  componentName: string,
+  options?: VoltraComponentOptions<TProps>
+): VoltraComponent<TProps> => {
+  const Component = (props: TProps) => {
+    const toJSON = options?.toJSON ? options.toJSON : (value: TProps) => value
+    const normalizedProps = toJSON(props)
+
+    return createElement(componentName, normalizedProps)
+  }
+
+  Component[VOLTRA_COMPONENT_TAG] = true
+  Component.displayName = componentName
+
+  return Component as VoltraComponent<TProps>
+}
+
+export const isVoltraComponent = <TProps extends Record<string, unknown>>(
+  component: ComponentType<TProps>
+): component is VoltraComponent<TProps> => {
+  return typeof component === 'function' && VOLTRA_COMPONENT_TAG in component
+}

package/src/payload/short-names.ts

@@ -0,0 +1,379 @@
+/* eslint-disable */
+// 🤖 AUTO-GENERATED from data/components.json
+// DO NOT EDIT MANUALLY - Changes will be overwritten
+// Schema version: 1.0.0
+
+/**
+ * Unified mapping from full names to short names
+ * Used for props and style properties
+ */
+export const NAME_TO_SHORT: Record<string, string> = {
+  absolutePosition: 'ap',
+  accentedRenderingMode: 'arm',
+  alignItems: 'ai',
+  alignment: 'al',
+  alignSelf: 'as',
+  alpha: 'a',
+  aspectRatio: 'ar',
+  assetName: 'an',
+  background: 'bkg',
+  backgroundColor: 'bg',
+  backgroundImage: 'bgi',
+  backgroundStyle: 'bgs',
+  base64: 'b64',
+  border: 'bd',
+  borderColor: 'bc',
+  borderRadius: 'br',
+  borderWidth: 'bw',
+  bottom: 'b',
+  buttonStyle: 'bs',
+  chartScrollableAxes: 'csa',
+  checked: 'chk',
+  checkedColor: 'chc',
+  clipped: 'clip',
+  color: 'c',
+  colorFilter: 'cf',
+  colors: 'cls',
+  columns: 'cols',
+  contentAlignment: 'ca',
+  contentColor: 'cc',
+  contentDescription: 'cdesc',
+  contentScale: 'csc',
+  cornerRadius: 'cr',
+  countDown: 'cd',
+  currentValueLabel: 'cvl',
+  deepLinkUrl: 'dlu',
+  defaultValue: 'dv',
+  destination: 'dest',
+  direction: 'dir',
+  dither: 'dth',
+  durationMs: 'dur',
+  enabled: 'en',
+  endAtMs: 'end',
+  endPoint: 'ep',
+  fallback: 'flb',
+  fillMaxHeight: 'fmh',
+  fillMaxWidth: 'fmw',
+  fixedSizeHorizontal: 'fsh',
+  fixedSizeVertical: 'fsv',
+  flex: 'fl',
+  flexBasis: 'fb',
+  flexDirection: 'fdir',
+  flexGrow: 'fg',
+  flexGrowWidth: 'fgw',
+  flexShrink: 'fk',
+  font: 'fnt',
+  fontFamily: 'ff',
+  fontSize: 'fs',
+  fontVariant: 'fvar',
+  fontWeight: 'fw',
+  foregroundStyle: 'fgs',
+  foregroundStyleScale: 'fss',
+  frame: 'f',
+  gap: 'g',
+  gaugeStyle: 'gs',
+  glassEffect: 'ge',
+  height: 'h',
+  horizontalAlignment: 'halig',
+  horizontalPadding: 'hp',
+  icon: 'ic',
+  iconColor: 'icc',
+  id: 'id',
+  italic: 'it',
+  justifyContent: 'jc',
+  kerning: 'kern',
+  label: 'lbl',
+  layout: 'ly',
+  layoutPriority: 'lp',
+  left: 'l',
+  legendVisibility: 'lgv',
+  letterSpacing: 'ls',
+  lineHeight: 'lh',
+  lineLimit: 'll',
+  lineSpacing: 'lsp',
+  lineWidth: 'lw',
+  margin: 'm',
+  marginBottom: 'mb',
+  marginHorizontal: 'mh',
+  marginLeft: 'ml',
+  marginRight: 'mr',
+  marginTop: 'mt',
+  marginVertical: 'mv',
+  marks: 'mrk',
+  maskElement: 'me',
+  maxHeight: 'maxh',
+  maximumValue: 'max',
+  maximumValueLabel: 'maxl',
+  maxLines: 'mxl',
+  maxWidth: 'maxw',
+  minHeight: 'minh',
+  minimumValue: 'min',
+  minimumValueLabel: 'minvl',
+  minLength: 'minl',
+  minWidth: 'minw',
+  monospacedDigit: 'md',
+  multilineTextAlignment: 'mta',
+  name: 'n',
+  numberOfLines: 'nol',
+  offset: 'off',
+  offsetX: 'ox',
+  offsetY: 'oy',
+  opacity: 'op',
+  overflow: 'ov',
+  padding: 'pad',
+  paddingBottom: 'pb',
+  paddingHorizontal: 'ph',
+  paddingLeft: 'pl',
+  paddingRight: 'pr',
+  paddingTop: 'pt',
+  paddingVertical: 'pv',
+  position: 'pos',
+  progress: 'prg',
+  progressColor: 'pc',
+  resizeMode: 'rm',
+  right: 'r',
+  rotationEffect: 're',
+  scale: 'sc',
+  scaleEffect: 'sce',
+  shadow: 'sh',
+  shadowColor: 'shc',
+  shadowOffset: 'sho',
+  shadowOpacity: 'shop',
+  shadowRadius: 'shr',
+  showHours: 'shrs',
+  size: 'sz',
+  smallCaps: 'smc',
+  source: 'src',
+  spacing: 'sp',
+  startAtMs: 'start',
+  startIcon: 'sic',
+  startPoint: 'stp',
+  stops: 'sts',
+  strikethrough: 'st',
+  style: 's',
+  systemImage: 'si',
+  text: 'txt',
+  textAlign: 'ta',
+  textColor: 'txc',
+  textDecorationLine: 'tdl',
+  textStyle: 'ts',
+  textTemplates: 'tt',
+  thumb: 'th',
+  thumbCheckedColor: 'thc',
+  thumbUncheckedColor: 'thu',
+  tint: 'tnt',
+  tintColor: 'tc',
+  title: 'ttl',
+  top: 't',
+  trackCheckedColor: 'trkc',
+  trackColor: 'trc',
+  trackUncheckedColor: 'trku',
+  transform: 'tf',
+  type: 'typ',
+  uncheckedColor: 'uchc',
+  underline: 'ul',
+  value: 'v',
+  verticalAlignment: 'valig',
+  weight: 'wt',
+  width: 'w',
+  xAxisGridStyle: 'xgs',
+  xAxisVisibility: 'xav',
+  yAxisGridStyle: 'ygs',
+  yAxisVisibility: 'yav',
+  zIndex: 'zi',
+}
+
+/**
+ * Reverse mapping from short names to full names
+ */
+export const SHORT_TO_NAME: Record<string, string> = {
+  ap: 'absolutePosition',
+  arm: 'accentedRenderingMode',
+  ai: 'alignItems',
+  al: 'alignment',
+  as: 'alignSelf',
+  a: 'alpha',
+  ar: 'aspectRatio',
+  an: 'assetName',
+  bkg: 'background',
+  bg: 'backgroundColor',
+  bgi: 'backgroundImage',
+  bgs: 'backgroundStyle',
+  b64: 'base64',
+  bd: 'border',
+  bc: 'borderColor',
+  br: 'borderRadius',
+  bw: 'borderWidth',
+  b: 'bottom',
+  bs: 'buttonStyle',
+  csa: 'chartScrollableAxes',
+  chk: 'checked',
+  chc: 'checkedColor',
+  clip: 'clipped',
+  c: 'color',
+  cf: 'colorFilter',
+  cls: 'colors',
+  cols: 'columns',
+  ca: 'contentAlignment',
+  cc: 'contentColor',
+  cdesc: 'contentDescription',
+  csc: 'contentScale',
+  cr: 'cornerRadius',
+  cd: 'countDown',
+  cvl: 'currentValueLabel',
+  dlu: 'deepLinkUrl',
+  dv: 'defaultValue',
+  dest: 'destination',
+  dir: 'direction',
+  dth: 'dither',
+  dur: 'durationMs',
+  en: 'enabled',
+  end: 'endAtMs',
+  ep: 'endPoint',
+  flb: 'fallback',
+  fmh: 'fillMaxHeight',
+  fmw: 'fillMaxWidth',
+  fsh: 'fixedSizeHorizontal',
+  fsv: 'fixedSizeVertical',
+  fl: 'flex',
+  fb: 'flexBasis',
+  fdir: 'flexDirection',
+  fg: 'flexGrow',
+  fgw: 'flexGrowWidth',
+  fk: 'flexShrink',
+  fnt: 'font',
+  ff: 'fontFamily',
+  fs: 'fontSize',
+  fvar: 'fontVariant',
+  fw: 'fontWeight',
+  fgs: 'foregroundStyle',
+  fss: 'foregroundStyleScale',
+  f: 'frame',
+  g: 'gap',
+  gs: 'gaugeStyle',
+  ge: 'glassEffect',
+  h: 'height',
+  halig: 'horizontalAlignment',
+  hp: 'horizontalPadding',
+  ic: 'icon',
+  icc: 'iconColor',
+  id: 'id',
+  it: 'italic',
+  jc: 'justifyContent',
+  kern: 'kerning',
+  lbl: 'label',
+  ly: 'layout',
+  lp: 'layoutPriority',
+  l: 'left',
+  lgv: 'legendVisibility',
+  ls: 'letterSpacing',
+  lh: 'lineHeight',
+  ll: 'lineLimit',
+  lsp: 'lineSpacing',
+  lw: 'lineWidth',
+  m: 'margin',
+  mb: 'marginBottom',
+  mh: 'marginHorizontal',
+  ml: 'marginLeft',
+  mr: 'marginRight',
+  mt: 'marginTop',
+  mv: 'marginVertical',
+  mrk: 'marks',
+  me: 'maskElement',
+  maxh: 'maxHeight',
+  max: 'maximumValue',
+  maxl: 'maximumValueLabel',
+  mxl: 'maxLines',
+  maxw: 'maxWidth',
+  minh: 'minHeight',
+  min: 'minimumValue',
+  minvl: 'minimumValueLabel',
+  minl: 'minLength',
+  minw: 'minWidth',
+  md: 'monospacedDigit',
+  mta: 'multilineTextAlignment',
+  n: 'name',
+  nol: 'numberOfLines',
+  off: 'offset',
+  ox: 'offsetX',
+  oy: 'offsetY',
+  op: 'opacity',
+  ov: 'overflow',
+  pad: 'padding',
+  pb: 'paddingBottom',
+  ph: 'paddingHorizontal',
+  pl: 'paddingLeft',
+  pr: 'paddingRight',
+  pt: 'paddingTop',
+  pv: 'paddingVertical',
+  pos: 'position',
+  prg: 'progress',
+  pc: 'progressColor',
+  rm: 'resizeMode',
+  r: 'right',
+  re: 'rotationEffect',
+  sc: 'scale',
+  sce: 'scaleEffect',
+  sh: 'shadow',
+  shc: 'shadowColor',
+  sho: 'shadowOffset',
+  shop: 'shadowOpacity',
+  shr: 'shadowRadius',
+  shrs: 'showHours',
+  sz: 'size',
+  smc: 'smallCaps',
+  src: 'source',
+  sp: 'spacing',
+  start: 'startAtMs',
+  sic: 'startIcon',
+  stp: 'startPoint',
+  sts: 'stops',
+  st: 'strikethrough',
+  s: 'style',
+  si: 'systemImage',
+  txt: 'text',
+  ta: 'textAlign',
+  txc: 'textColor',
+  tdl: 'textDecorationLine',
+  ts: 'textStyle',
+  tt: 'textTemplates',
+  th: 'thumb',
+  thc: 'thumbCheckedColor',
+  thu: 'thumbUncheckedColor',
+  tnt: 'tint',
+  tc: 'tintColor',
+  ttl: 'title',
+  t: 'top',
+  trkc: 'trackCheckedColor',
+  trc: 'trackColor',
+  trku: 'trackUncheckedColor',
+  tf: 'transform',
+  typ: 'type',
+  uchc: 'uncheckedColor',
+  ul: 'underline',
+  v: 'value',
+  valig: 'verticalAlignment',
+  wt: 'weight',
+  w: 'width',
+  xgs: 'xAxisGridStyle',
+  xav: 'xAxisVisibility',
+  ygs: 'yAxisGridStyle',
+  yav: 'yAxisVisibility',
+  zi: 'zIndex',
+}
+
+/**
+ * Shorten a name using the unified mapping
+ * Returns the original name if no short form exists
+ */
+export function shorten(name: string): string {
+  return NAME_TO_SHORT[name] ?? name
+}
+
+/**
+ * Expand a short name back to the full name
+ * Returns the original value if no expansion exists
+ */
+export function expand(short: string): string {
+  return SHORT_TO_NAME[short] ?? short
+}

package/src/payload.ts

@@ -0,0 +1,23 @@
+const MAX_ACTIVITYKIT_BYTES = 4096
+const EFFECTIVE_JSON_BUDGET = 3345
+
+const utf8ByteLength = (s: string): number => {
+  try {
+    if (typeof TextEncoder !== 'undefined') return new TextEncoder().encode(s).length
+  } catch {}
+  try {
+    return encodeURI(s).replace(/%[A-F\d]{2}/gi, 'X').length
+  } catch {
+    return s.length
+  }
+}
+
+export const ensurePayloadWithinBudget = (compressedPayload: string): void => {
+  const bytes = utf8ByteLength(compressedPayload)
+
+  if (bytes > EFFECTIVE_JSON_BUDGET) {
+    throw new Error(
+      `[Voltra] Compressed payload size ${bytes}B exceeds safe budget ${EFFECTIVE_JSON_BUDGET}B (ActivityKit hard cap ${MAX_ACTIVITYKIT_BYTES}B). You need to reduce the complexity of your UI.`
+    )
+  }
+}