lynx-pretext-devtools 0.0.1

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "lynx-pretext-devtools",
+  "version": "0.0.1",
+  "description": "Developer tools and debugging components for lynx-pretext",
+  "license": "MIT",
+  "author": "Huxpro",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Huxpro/lynx-pretext.git",
+    "directory": "packages/lynx-pretext-devtools"
+  },
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --build"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src"],
+  "keywords": [
+    "lynx",
+    "devtools",
+    "debug",
+    "performance"
+  ],
+  "peerDependencies": {
+    "@lynx-js/react": ">=0.116.0",
+    "@lynx-js/types": ">=3.7.0"
+  },
+  "devDependencies": {
+    "@lynx-js/react": "0.116.4",
+    "@lynx-js/types": "3.7.0",
+    "@types/react": "^18.3.28",
+    "typescript": "~5.9.3"
+  }
+}

package/src/components/DevPanelActions.tsx

@@ -0,0 +1,18 @@
+import type { DevPanelActionsProps } from '../types'
+
+export function DevPanelActions({
+  children,
+}: DevPanelActionsProps): React.ReactElement {
+  return (
+    <view
+      style={{
+        display: 'flex',
+        flexDirection: 'row',
+        marginTop: '6px',
+        gap: '6px',
+      }}
+    >
+      {children}
+    </view>
+  )
+}

package/src/components/DevPanelButton.tsx

@@ -0,0 +1,34 @@
+import { useCallback } from '@lynx-js/react'
+import { TEXT_PRIMARY, BUTTON_BG, BUTTON_ACTIVE, STEPPER_RADIUS } from '../constants'
+import type { DevPanelButtonProps } from '../types'
+
+export function DevPanelButton({
+  label,
+  active = false,
+  onPress,
+}: DevPanelButtonProps): React.ReactElement {
+  const handlePress = useCallback(() => {
+    onPress()
+  }, [onPress])
+
+  return (
+    <view
+      bindtap={handlePress}
+      style={{
+        display: 'flex',
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: '22px',
+        paddingLeft: '8px',
+        paddingRight: '8px',
+        borderRadius: STEPPER_RADIUS,
+        backgroundColor: active ? BUTTON_ACTIVE : BUTTON_BG,
+      }}
+    >
+      <text style={{ fontSize: '10px', color: TEXT_PRIMARY, fontFamily: 'monospace' }}>
+        {label}
+      </text>
+    </view>
+  )
+}

package/src/components/DevPanelContent.tsx

@@ -0,0 +1,53 @@
+import { useDevPanelContext } from '../context'
+import { PANEL_BG, PANEL_RADIUS, PANEL_PADDING, TEXT_PRIMARY, TEXT_SECONDARY, PANEL_TOP } from '../constants'
+import type { DevPanelContentProps } from '../types'
+
+export function DevPanelContent({
+  title,
+  description,
+  children,
+}: DevPanelContentProps): React.ReactElement | null {
+  const { open } = useDevPanelContext()
+
+  if (!open) return null
+
+  return (
+    <view
+      style={{
+        position: 'absolute',
+        top: PANEL_TOP,
+        right: '8px',
+        minWidth: '140px',
+        backgroundColor: PANEL_BG,
+        borderRadius: PANEL_RADIUS,
+        padding: PANEL_PADDING,
+      }}
+    >
+      {title && (
+        <text style={{
+          fontSize: '10px',
+          color: TEXT_SECONDARY,
+          fontFamily: 'monospace',
+          textTransform: 'uppercase',
+          letterSpacing: '0.5px',
+          marginBottom: '6px',
+        }}>
+          {title}
+        </text>
+      )}
+      {description && (
+        <text
+          style={{
+            fontSize: '10px',
+            color: TEXT_SECONDARY,
+            marginTop: '2px',
+            lineHeight: '14px',
+          }}
+        >
+          {description}
+        </text>
+      )}
+      {children}
+    </view>
+  )
+}

package/src/components/DevPanelFPS.tsx

@@ -0,0 +1,56 @@
+import type { MainThreadRef } from '@lynx-js/react'
+import type { MainThread } from '@lynx-js/types'
+import { getFpsColor, TEXT_TERTIARY, TEXT_SECONDARY } from '../constants'
+
+export interface DevPanelFPSProps {
+  mtsFpsDisplay: number
+  btsFpsDisplay: number
+  mtsFpsTextRef?: MainThreadRef<MainThread.Element | null>
+}
+
+export function DevPanelFPS({
+  mtsFpsDisplay,
+  btsFpsDisplay,
+  mtsFpsTextRef,
+}: DevPanelFPSProps): React.ReactElement {
+  return (
+    <view
+      style={{
+        display: 'flex',
+        flexDirection: 'row',
+        marginTop: '6px',
+        gap: '12px',
+        alignItems: 'center',
+      }}
+    >
+      {/* MTS FPS */}
+      <view style={{ display: 'flex', flexDirection: 'row', alignItems: 'baseline', gap: '3px' }}>
+        <text style={{ fontSize: '9px', color: TEXT_TERTIARY, fontFamily: 'monospace' }}>M</text>
+        <text
+          main-thread:ref={mtsFpsTextRef}
+          style={{
+            fontSize: '11px',
+            fontFamily: 'monospace',
+            color: getFpsColor(mtsFpsDisplay),
+          }}
+        >
+          {`${mtsFpsDisplay}`}
+        </text>
+      </view>
+
+      {/* BTS FPS */}
+      <view style={{ display: 'flex', flexDirection: 'row', alignItems: 'baseline', gap: '3px' }}>
+        <text style={{ fontSize: '9px', color: TEXT_TERTIARY, fontFamily: 'monospace' }}>B</text>
+        <text
+          style={{
+            fontSize: '11px',
+            fontFamily: 'monospace',
+            color: getFpsColor(btsFpsDisplay),
+          }}
+        >
+          {`${btsFpsDisplay}`}
+        </text>
+      </view>
+    </view>
+  )
+}

package/src/components/DevPanelRoot.tsx

@@ -0,0 +1,13 @@
+import { DevPanelProvider } from '../context'
+import type { DevPanelRootProps } from '../types'
+
+export function DevPanelRoot({
+  children,
+  defaultOpen = false,
+}: DevPanelRootProps): React.ReactElement {
+  return (
+    <DevPanelProvider defaultOpen={defaultOpen}>
+      {children}
+    </DevPanelProvider>
+  )
+}

package/src/components/DevPanelStat.tsx

@@ -0,0 +1,16 @@
+import { TEXT_PRIMARY, TEXT_TERTIARY } from '../constants'
+import type { DevPanelStatProps } from '../types'
+
+export function DevPanelStat({
+  label,
+  value,
+}: DevPanelStatProps): React.ReactElement {
+  return (
+    <view style={{ display: 'flex', flexDirection: 'row', alignItems: 'baseline', gap: '4px' }}>
+      <text style={{ fontSize: '9px', color: TEXT_TERTIARY, fontFamily: 'monospace' }}>{label}</text>
+      <text style={{ fontSize: '11px', fontFamily: 'monospace', color: TEXT_PRIMARY }}>
+        {`${value}`}
+      </text>
+    </view>
+  )
+}

package/src/components/DevPanelStats.tsx

@@ -0,0 +1,18 @@
+import type { DevPanelStatsProps } from '../types'
+
+export function DevPanelStats({
+  children,
+}: DevPanelStatsProps): React.ReactElement {
+  return (
+    <view
+      style={{
+        display: 'flex',
+        flexDirection: 'row',
+        gap: '10px',
+        marginTop: '6px',
+      }}
+    >
+      {children}
+    </view>
+  )
+}

package/src/components/DevPanelStepper.tsx

@@ -0,0 +1,82 @@
+import { useCallback } from '@lynx-js/react'
+import {
+  STEPPER_BG,
+  STEPPER_SIZE,
+  STEPPER_RADIUS,
+  TEXT_PRIMARY,
+  TEXT_SECONDARY,
+  TEXT_TERTIARY,
+} from '../constants'
+import type { DevPanelStepperProps } from '../types'
+
+export function DevPanelStepper({
+  label,
+  value,
+  min = -Infinity,
+  max = Infinity,
+  step = 1,
+  unit = 'px',
+  onChange,
+}: DevPanelStepperProps): React.ReactElement {
+  const canDecrease = value > min
+  const canIncrease = value < max
+
+  const decrease = useCallback(() => {
+    if (canDecrease) {
+      onChange(Math.max(min, value - step))
+    }
+  }, [value, min, step, onChange, canDecrease])
+
+  const increase = useCallback(() => {
+    if (canIncrease) {
+      onChange(Math.min(max, value + step))
+    }
+  }, [value, max, step, onChange, canIncrease])
+
+  const buttonStyle = (enabled: boolean) => ({
+    width: STEPPER_SIZE,
+    height: STEPPER_SIZE,
+    borderRadius: STEPPER_RADIUS,
+    backgroundColor: enabled ? STEPPER_BG : 'transparent',
+    alignItems: 'center' as const,
+    justifyContent: 'center' as const,
+  })
+
+  return (
+    <view
+      style={{
+        display: 'flex',
+        flexDirection: 'row',
+        alignItems: 'center',
+        marginTop: '6px',
+        gap: '6px',
+      }}
+    >
+      <text style={{ fontSize: '9px', color: TEXT_SECONDARY, fontFamily: 'monospace' }}>{label}</text>
+
+      <view bindtap={decrease} style={buttonStyle(canDecrease)}>
+        <text style={{ fontSize: '12px', color: canDecrease ? TEXT_PRIMARY : TEXT_TERTIARY, fontFamily: 'monospace', lineHeight: '14px' }}>
+          {'\u2212'}
+        </text>
+      </view>
+
+      <text
+        style={{
+          fontSize: '10px',
+          color: TEXT_PRIMARY,
+          fontFamily: 'monospace',
+          minWidth: '40px',
+          textAlign: 'center',
+        }}
+      >
+        {`${value}${unit}`}
+      </text>
+
+      <view bindtap={increase} style={buttonStyle(canIncrease)}>
+        <text style={{ fontSize: '12px', color: canIncrease ? TEXT_PRIMARY : TEXT_TERTIARY, fontFamily: 'monospace', lineHeight: '14px' }}>
+          +
+        </text>
+      </view>
+    </view>
+  )
+}

package/src/components/DevPanelTrigger.tsx

@@ -0,0 +1,46 @@
+import { useCallback } from '@lynx-js/react'
+import { useDevPanelContext } from '../context'
+import {
+  TRIGGER_SIZE,
+  TRIGGER_RADIUS,
+  TRIGGER_BG_OPEN,
+  TRIGGER_BG_CLOSED,
+  TEXT_PRIMARY,
+  SAFE_AREA_TOP,
+} from '../constants'
+
+export function DevPanelTrigger(): React.ReactElement {
+  const { open, setOpen } = useDevPanelContext()
+
+  const toggle = useCallback(() => {
+    setOpen(!open)
+  }, [open, setOpen])
+
+  return (
+    <view
+      bindtap={toggle}
+      style={{
+        position: 'absolute',
+        top: SAFE_AREA_TOP,
+        right: '8px',
+        width: TRIGGER_SIZE,
+        height: TRIGGER_SIZE,
+        borderRadius: TRIGGER_RADIUS,
+        backgroundColor: open ? TRIGGER_BG_OPEN : TRIGGER_BG_CLOSED,
+        alignItems: 'center',
+        justifyContent: 'center',
+      }}
+    >
+      <text
+        style={{
+          fontSize: '12px',
+          color: TEXT_PRIMARY,
+          fontFamily: 'monospace',
+          lineHeight: '14px',
+        }}
+      >
+        {open ? '\u00D7' : '\u2630'}
+      </text>
+    </view>
+  )
+}

package/src/constants.ts

@@ -0,0 +1,40 @@
+// Panel styling - minimalist devtool aesthetic
+export const PANEL_BG = 'rgba(0,0,0,0.88)'
+export const PANEL_RADIUS = '6px'
+export const PANEL_PADDING = '8px'
+
+// Safe area - iOS status bar height
+export const SAFE_AREA_TOP = '48px'
+
+// Trigger button - smaller, more subtle
+export const TRIGGER_SIZE = '24px'
+export const TRIGGER_RADIUS = '4px'
+export const TRIGGER_BG_OPEN = 'rgba(0,0,0,0.85)'
+export const TRIGGER_BG_CLOSED = 'rgba(0,0,0,0.18)' // More subtle when not active
+
+// Panel content position (below trigger)
+export const PANEL_TOP = '80px' // SAFE_AREA_TOP + TRIGGER_SIZE + 8px gap
+
+// Text colors - muted, devtool-like
+export const TEXT_PRIMARY = 'rgba(255,255,255,0.92)'
+export const TEXT_SECONDARY = 'rgba(255,255,255,0.55)'
+export const TEXT_TERTIARY = 'rgba(255,255,255,0.38)'
+
+// FPS color coding - subtle, not harsh
+export const FPS_GREEN = 'rgba(129,199,132,0.9)'
+export const FPS_ORANGE = 'rgba(255,183,77,0.9)'
+export const FPS_RED = 'rgba(229,115,115,0.9)'
+
+// Stepper - compact
+export const STEPPER_BG = 'rgba(255,255,255,0.08)'
+export const STEPPER_SIZE = '20px'
+export const STEPPER_RADIUS = '3px'
+
+// Button
+export const BUTTON_BG = 'rgba(255,255,255,0.06)'
+export const BUTTON_ACTIVE = 'rgba(255,255,255,0.15)'
+
+// Helper: get FPS color based on value
+export function getFpsColor(fps: number): string {
+  return fps >= 50 ? FPS_GREEN : fps >= 30 ? FPS_ORANGE : FPS_RED
+}

package/src/context.tsx

@@ -0,0 +1,30 @@
+import { createContext, useContext, useState } from '@lynx-js/react'
+import type { DevPanelContextValue } from './types'
+
+const DevPanelContext = createContext<DevPanelContextValue | null>(null)
+
+export function useDevPanelContext(): DevPanelContextValue {
+  const ctx = useContext(DevPanelContext)
+  if (!ctx) {
+    throw new Error('DevPanel components must be used within DevPanel.Root')
+  }
+  return ctx
+}
+
+export interface DevPanelProviderProps {
+  children: React.ReactNode
+  defaultOpen?: boolean
+}
+
+export function DevPanelProvider({
+  children,
+  defaultOpen = false,
+}: DevPanelProviderProps): React.ReactElement {
+  const [open, setOpen] = useState(defaultOpen)
+
+  return (
+    <DevPanelContext.Provider value={{ open, setOpen }}>
+      {children}
+    </DevPanelContext.Provider>
+  )
+}

package/src/hooks/useDevPanelFPS.ts

@@ -0,0 +1,79 @@
+import { useRef, useMainThreadRef, runOnBackground, useState } from '@lynx-js/react'
+import type { MainThreadRef } from '@lynx-js/react'
+import type { MainThread } from '@lynx-js/types'
+
+export interface UseDevPanelFPSReturn {
+  mtsFpsTick: () => void
+  btsFpsTick: () => void
+  mtsFpsDisplay: number
+  btsFpsDisplay: number
+  mtsFpsTextRef: MainThreadRef<MainThread.Element | null>
+}
+
+export function useDevPanelFPS(mtsDirectUpdate = false): UseDevPanelFPSReturn {
+  // Display state (for React render)
+  const [mtsFpsDisplay, setMtsFpsDisplay] = useState(0)
+  const [btsFpsDisplay, setBtsFpsDisplay] = useState(0)
+
+  // MTS refs for frame counting
+  const mtsFrameCountRef = useMainThreadRef(0)
+  const mtsLastTimeRef = useMainThreadRef(0)
+
+  // BTS refs for frame counting
+  const btsFrameCountRef = useRef(0)
+  const btsLastTimeRef = useRef(0)
+
+  // MTS direct update ref (for mtsDirectUpdate mode)
+  // Must use useMainThreadRef since it's passed to main-thread:ref
+  const mtsFpsTextRef = useMainThreadRef<MainThread.Element | null>(null)
+
+  // MTS tick function - must have 'main thread' directive first
+  function mtsFpsTick(): void {
+    'main thread'
+    mtsFrameCountRef.current++
+    const now = Date.now()
+    if (mtsLastTimeRef.current === 0) {
+      mtsLastTimeRef.current = now
+    }
+    const elapsed = now - mtsLastTimeRef.current
+
+    if (elapsed >= 500) {
+      const fps = Math.round((mtsFrameCountRef.current / elapsed) * 1000)
+      mtsFrameCountRef.current = 0
+      mtsLastTimeRef.current = now
+
+      // Direct update mode: update text element directly on MTS
+      if (mtsDirectUpdate && mtsFpsTextRef.current) {
+        mtsFpsTextRef.current.setAttribute('text', `${fps}`)
+      }
+
+      // Push to BTS for state (used by color coding)
+      runOnBackground(setMtsFpsDisplay)(fps)
+    }
+  }
+
+  // BTS tick function - plain function
+  function btsFpsTick(): void {
+    btsFrameCountRef.current++
+    const now = Date.now()
+    if (btsLastTimeRef.current === 0) {
+      btsLastTimeRef.current = now
+    }
+    const elapsed = now - btsLastTimeRef.current
+
+    if (elapsed >= 500) {
+      const fps = Math.round((btsFrameCountRef.current / elapsed) * 1000)
+      btsFrameCountRef.current = 0
+      btsLastTimeRef.current = now
+      setBtsFpsDisplay(fps)
+    }
+  }
+
+  return {
+    mtsFpsTick,
+    btsFpsTick,
+    mtsFpsDisplay,
+    btsFpsDisplay,
+    mtsFpsTextRef,
+  }
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+// Context
+export { DevPanelProvider, useDevPanelContext } from './context'
+
+// Types
+export type {
+  DevPanelRootProps,
+  DevPanelContentProps,
+  DevPanelStatProps,
+  DevPanelStepperProps,
+  DevPanelButtonProps,
+  DevPanelStatsProps,
+  DevPanelActionsProps,
+  DevPanelContextValue,
+} from './types'
+
+// Hook
+export { useDevPanelFPS } from './hooks/useDevPanelFPS'
+export type { UseDevPanelFPSReturn } from './hooks/useDevPanelFPS'
+
+// FPS Component (requires props from hook)
+export { DevPanelFPS } from './components/DevPanelFPS'
+export type { DevPanelFPSProps } from './components/DevPanelFPS'
+
+// Constants (for advanced customization)
+export {
+  PANEL_BG,
+  PANEL_RADIUS,
+  PANEL_PADDING,
+  PANEL_TOP,
+  SAFE_AREA_TOP,
+  TRIGGER_SIZE,
+  TRIGGER_RADIUS,
+  TRIGGER_BG_OPEN,
+  TRIGGER_BG_CLOSED,
+  TEXT_PRIMARY,
+  TEXT_SECONDARY,
+  TEXT_TERTIARY,
+  FPS_GREEN,
+  FPS_ORANGE,
+  FPS_RED,
+  STEPPER_BG,
+  STEPPER_SIZE,
+  STEPPER_RADIUS,
+  BUTTON_BG,
+  BUTTON_ACTIVE,
+  getFpsColor,
+} from './constants'
+
+// Components
+import { DevPanelRoot } from './components/DevPanelRoot'
+import { DevPanelTrigger } from './components/DevPanelTrigger'
+import { DevPanelContent } from './components/DevPanelContent'
+import { DevPanelFPS } from './components/DevPanelFPS'
+import { DevPanelStats } from './components/DevPanelStats'
+import { DevPanelStat } from './components/DevPanelStat'
+import { DevPanelStepper } from './components/DevPanelStepper'
+import { DevPanelActions } from './components/DevPanelActions'
+import { DevPanelButton } from './components/DevPanelButton'
+
+// Namespace assembly (Radix-style compound component API)
+export const DevPanel = {
+  Root: DevPanelRoot,
+  Trigger: DevPanelTrigger,
+  Content: DevPanelContent,
+  FPS: DevPanelFPS,
+  Stats: DevPanelStats,
+  Stat: DevPanelStat,
+  Stepper: DevPanelStepper,
+  Actions: DevPanelActions,
+  Button: DevPanelButton,
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+import type { MainThread } from '@lynx-js/types'
+
+export interface DevPanelRootProps {
+  children: React.ReactNode
+  defaultOpen?: boolean
+}
+
+export interface DevPanelContentProps {
+  title: string
+  description?: string
+  children?: React.ReactNode
+}
+
+export interface DevPanelStatProps {
+  label: string
+  value: string | number
+}
+
+export interface DevPanelStepperProps {
+  label: string
+  value: number
+  min?: number
+  max?: number
+  step?: number
+  unit?: string
+  onChange: (value: number) => void
+}
+
+export interface DevPanelButtonProps {
+  label: string
+  active?: boolean
+  onPress: () => void
+}
+
+export interface DevPanelStatsProps {
+  children: React.ReactNode
+}
+
+export interface DevPanelActionsProps {
+  children: React.ReactNode
+}
+
+// Context types
+export interface DevPanelContextValue {
+  open: boolean
+  setOpen: (open: boolean) => void
+}