Skip to content

PRD.md

Latest commit

 

History

History
88 lines (68 loc) · 5.79 KB

PRD.md

File metadata and controls

88 lines (68 loc) · 5.79 KB
Raw

Product Requirements Document (PRD) — AppDimens Dynamic

Note

Version: 1.0.1 — modules: MODULES.md Related: PDR · Mathematics · API Conventions

1. Executive Summary

AppDimens Dynamic is a mathematical scaling engine for Kotlin Multiplatform (com.appdimens.kmp). Its purpose is to map generic UI dimensions (developed against a 300dp or equivalent reference) to physical window parameters—scaling elegantly across phones, tablets, desktop windows, and unpredictable foldables, on Android, JVM, iOS, macOS, the web (Kotlin/JS + wasmJs), Linux and Windows.

It encapsulates scaling strategies (curves) shipped as Maven modules, alongside an autonomous Resize/Constraint subsystem that finds the largest fitting size via binary search.

2. Market Context & Problem Space

Static dp measurements fall apart as device variety increases. A 300dp horizontal card fits perfectly on a classic phone but becomes aggressively small on high-density tablets or wide-screen foldables.

Core Objectives

  1. Mathematical Consistency: Provide reproducible scaling curves (Linear, Logarithmic, Power).
  2. Unified Surface APIs: Symmetrical integration rules for Compose Multiplatform (compose.*) and non-Compose code (code.*, with a platform-neutral AppDimensContext window handle).
  3. High-Frequency Performance: Accommodate zero-allocation hot paths using lock-free architecture for smooth 60FPS and 120FPS rendering algorithms.
  4. Hardware Awareness: Adapt directly to Configuration, Display aspect ratios, Multi-Window flags, and Context DPI.
  5. Modular APK control: Developers include only the strategy artifacts they need; the principal artifact must not pull all strategies.

3. Functional Architecture overview

mindmap
  root((AppDimens Dynamic))
    Mathematical Engine
      Linear & Scaled Defaults
      Logarithmic Deterioration
      Exponential / Power Curves
      Diagonal Vector Paths
    Resize Subsystem
      Binary Constraint Search
      Max Area Fits Predicate
      Zero-GC Floating Arrays
    Consumer Platforms
      Compose Multiplatform (Android/Desktop/iOS/macOS/Web) · `code` API also on Linux/Windows native
      Non-Compose code API (AppDimensContext)
      Pure Kotlin Math Core
    Thread Safe Cache Layer
      Snapshot-partitioned Cache
      Multi-Window Detection
      Atomic Reference Entries
Loading

4. Feature Requirements (FR)

FR-0: Systemic Foundation & Architecture

  • FR-0.1 (Module Separation): Each strategy must exist as an independent computational node. compose.percent cannot import compose.power.
  • FR-0.2 (Telemetry & Reading): Raw dimensions must derive from the platform window configuration — on Android from android.content.res.Configuration, on desktop/web/iOS/macOS from the live window/viewport snapshot exposed as ScreenConfiguration, and on Linux/Windows native from a ScreenConfiguration you build (no windowing API in the Kotlin/Native stdlib — defaultPlatformContext() returns null there).
  • FR-0.3 (Platform Parity): All Compose API nodes (*DpExtensions) must explicitly feature symmetric code equivalents for legacy migration.

FR-1: Dimension Mathematics & Curves

Tip

The Scaled default curve remains optimal for generic UI development, specifically supporting aspect-ratio injection (sdpa, sdpi) for anti-distortion tuning.

Strategy Class Mathematical Goal Expected Consumer Use Case
Scaled (Default) Linear geometry translation from basic 300dp scale. Baseline paddings, Standard containers.
Logarithmic Fast early growth curve with heavy downstream damping. Text geometries on massive tablets.
Fluid Breakpoint-based linear interpolation ([320..768]). Responsive Web-like UI adjustments.
Percent / Space Absolute device fractional limits (( % \times sw )). Fixed grid splits, Nav bars.
Interpolated Blend between base and linear scale (50%). Softer growth than pure linear.

FR-2: Engine & Subsystem Resize Algorithms

  • FR-2.1 (Memory Integrity): Generates constraint step buffers via static pre-allocated FloatArray. No auto-boxing allowed.
  • FR-2.2 (Processing): Operates on an asymptotic (\mathcal{O}(\log N)) binary search protocol to match element sizing to physical screen limits.
  • FR-2.3 (Bounds & Safety): Respect hardware metrics with ResizeBound.resolveToPx using strict require(density > 0) contracts.

5. Non-Functional Requirements (NFR)

  • NFR-1 (Performance Benchmarking): shouldBypassCache skips snapshot-cache I/O for multiply-only types (PERCENT, SCALED, DENSITY, DIAGONAL, INTERPOLATED, PERIMETER) and for POWER / LOGARITHMIC on the default SW path — including default aspect ratio when applicable. See library/PERFORMANCE.md.
  • NFR-2 (Lock-Free Threading): Lock-free, snapshot-partitioned cache. Each window/configuration snapshot (DimenMetrics) owns a fixed-size partition whose entries are published as a single immutable CacheEntry (key + value bits) through AtomicReferenceArray, so concurrent readers never observe another key’s value; no disk persistence.
  • NFR-3 (Minimum Environment): minSdk = 24, Java 17 requirements, enforcing direct Proguard shipping via consumer-rules.pro.
  • NFR-4 (Runtime Diagnostics): Engine observability functions remain conditionally gated (diagnosticsEnabled) to eliminate tracing overhead in production applications.

6. Metrics of Success

  1. Integration on both Compose/XML environments without memory/GC stuttering.
  2. Binary scale operations taking < 15ns median time.
  3. Successful scaling to multi-window split structures automatically.