{"_id":"@buildincredibles/arc","name":"@buildincredibles/arc","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@buildincredibles/arc","version":"0.1.0","description":"Adaptive Runtime Controller (ARC) for performance-aware frontends","license":"MIT","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup src/index.ts --format esm,cjs --dts --clean","dev":"tsup src/index.ts --watch --format esm,cjs --dts","prepublishOnly":"npm run build"},"peerDependencies":{"react":">=18"},"devDependencies":{"@types/react":"^19.2.14","tsup":"^8.5.1","typescript":"^5.9.3"},"gitHead":"7fa3179eb90996ccf814c0edb43c8b845148fbdd","_id":"@buildincredibles/arc@0.1.0","_nodeVersion":"22.20.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-djc/jac5yl2sUMFQ69rZD23JItJnsG0zDapSmdGmTpxTec86sx54AaaMchTJAuoR4MEWJnycVM59yY1DlfrHCQ==","shasum":"c0d7b1788c91e6820f3d1b1d4dacb4b1a95dbc05","tarball":"https://registry.npmjs.org/@buildincredibles/arc/-/arc-0.1.0.tgz","fileCount":7,"unpackedSize":19203,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDHatuNrP99RLLR0qrf0eiC7pLc4uAM6zZOD9dh5C5blAiBhgsCsKHl1/7PLAeVS23H6mfN4rT3yL4HyaD2TXXbXbQ=="}]},"_npmUser":{"name":"arhamsayyed","email":"buildincredibles@gmail.com"},"directories":{},"maintainers":[{"name":"arhamsayyed","email":"buildincredibles@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/arc_0.1.0_1772628608418_0.08494586307177765"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-04T12:50:08.311Z","0.1.0":"2026-03-04T12:50:08.565Z","modified":"2026-03-04T12:50:08.814Z"},"maintainers":[{"name":"arhamsayyed","email":"buildincredibles@gmail.com"}],"description":"Adaptive Runtime Controller (ARC) for performance-aware frontends","license":"MIT","readme":"# ARC\r\n\r\n### Adaptive Runtime Controller\r\n\r\nPerformance-aware runtime tier detection for React applications.\r\n\r\nARC is a lightweight runtime engine that measures real-world frontend performance and classifies a device into a performance tier. It enables React applications to adapt heavy UI features (animations, canvas, WebGL, effects) based on actual runtime behavior instead of assumptions.\r\n\r\nMaintained by **Build Incredibles**  \r\nhttps://buildincredibles.com\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @buildincredibles/arc\r\n```\r\n\r\nPeer dependency:\r\n\r\n```bash\r\nreact >= 18\r\n```\r\n\r\n---\r\n\r\n## Core Concept\r\n\r\nARC measures how the browser actually performs during a short probing window (default: 2000ms). It collects:\r\n\r\n- Frame timing via `requestAnimationFrame`\r\n- Long tasks via `PerformanceObserver`\r\n- Hardware information\r\n- WebGL support\r\n\r\nAfter probing completes, ARC computes a performance tier and exposes the result through a React context.\r\n\r\nARC does not automatically change anything in your UI. It only exposes state. You decide how to adapt.\r\n\r\n---\r\n\r\n## What ARC Measures\r\n\r\n### 1. Frame Times\r\n\r\nEach animation frame duration is recorded using `requestAnimationFrame`.\r\n\r\nIf frames consistently exceed ~16ms (ideal 60fps frame time), performance is constrained.\r\n\r\nFrame times are used to compute:\r\n\r\n- Average FPS\r\n- Dropped frame percentage\r\n\r\n---\r\n\r\n### 2. Average FPS (`avgFps`)\r\n\r\nCalculated as:\r\n\r\n```\r\n1000 / averageFrameTime\r\n```\r\n\r\nHigher FPS indicates smoother rendering.\r\n\r\nTypical ranges:\r\n\r\n- 55–60 FPS → Excellent\r\n- 45–55 FPS → Good\r\n- 30–45 FPS → Moderate\r\n- <30 FPS → Constrained\r\n\r\n---\r\n\r\n### 3. Dropped Frame Percentage (`droppedFramePercent`)\r\n\r\nDefined as:\r\n\r\n```\r\npercentage of frames exceeding 20ms\r\n```\r\n\r\nThis indicates how often the browser fails to maintain smooth rendering.\r\n\r\nLower is better.\r\n\r\n---\r\n\r\n### 4. Long Tasks (`longTasks`)\r\n\r\nTracked using `PerformanceObserver` with `entryTypes: [\"longtask\"]`.\r\n\r\nA long task is a task blocking the main thread for >50ms.\r\n\r\nHigher counts indicate:\r\n\r\n- Heavy JavaScript execution\r\n- Blocking layout work\r\n- Expensive synchronous operations\r\n\r\n---\r\n\r\n### 5. Hardware Concurrency (`hardwareConcurrency`)\r\n\r\nFrom:\r\n\r\n```\r\nnavigator.hardwareConcurrency\r\n```\r\n\r\nRepresents logical CPU cores available.\r\n\r\n---\r\n\r\n### 6. Device Memory (`deviceMemory`)\r\n\r\nFrom:\r\n\r\n```\r\nnavigator.deviceMemory\r\n```\r\n\r\nApproximate RAM in GB (if supported).\r\n\r\nOptional and browser-dependent.\r\n\r\n---\r\n\r\n### 7. WebGL Support (`webgl`)\r\n\r\nChecks for WebGL2 context availability.\r\n\r\nIndicates whether GPU-accelerated rendering is supported.\r\n\r\n---\r\n\r\n## Performance Tiers\r\n\r\nAfter probing, ARC assigns one of the following tiers:\r\n\r\n| Tier    | Condition                                |\r\n| ------- | ---------------------------------------- |\r\n| probing | Initial measurement phase                |\r\n| ultra   | avgFps > 55 AND droppedFramePercent < 10 |\r\n| high    | avgFps > 45                              |\r\n| medium  | avgFps > 30                              |\r\n| low     | Otherwise                                |\r\n\r\nTier selection is based only on measured metrics unless overridden manually.\r\n\r\n---\r\n\r\n## State Model\r\n\r\nARC exposes the following state:\r\n\r\n```ts\r\ninterface ArcState {\r\n  tier: ArcTier\r\n  metrics: ArcMetrics\r\n  stable: boolean\r\n  overridden: boolean\r\n}\r\n```\r\n\r\n---\r\n\r\n### `tier`\r\n\r\nCurrent performance classification.\r\n\r\nPossible values:\r\n\r\n```ts\r\n\"type ArcTier = 'probing' | 'ultra' | 'high' | 'medium' | 'low'\"\r\n```\r\n\r\n---\r\n\r\n### `metrics`\r\n\r\n```ts\r\ninterface ArcMetrics {\r\n  avgFps: number\r\n  droppedFramePercent: number\r\n  longTasks: number\r\n  hardwareConcurrency: number\r\n  deviceMemory?: number\r\n  webgl: boolean\r\n}\r\n```\r\n\r\nContains all measured runtime data.\r\n\r\n---\r\n\r\n### `stable`\r\n\r\nBoolean indicating whether the probing phase has completed.\r\n\r\n- `false` → Still measuring performance\r\n- `true` → Tier is finalized\r\n\r\nARC becomes stable after `probeDuration` (default 2000ms).\r\n\r\nYou can use this to avoid rendering tier-dependent UI prematurely.\r\n\r\nExample:\r\n\r\n```tsx\r\nconst { stable } = useArc()\r\n\r\nif (!stable) return null\r\n```\r\n\r\n---\r\n\r\n### `overridden`\r\n\r\nIndicates whether the current tier is manually forced.\r\n\r\n- `true` → Tier was set using override\r\n- `false` → Tier determined automatically\r\n\r\n---\r\n\r\n## React Usage\r\n\r\n### 1. Wrap Application\r\n\r\n```tsx\r\nimport { ArcProvider } from '@buildincredibles/arc'\r\n\r\nfunction App() {\r\n  return (\r\n    <ArcProvider>\r\n      <Root />\r\n    </ArcProvider>\r\n  )\r\n}\r\n```\r\n\r\n---\r\n\r\n### 2. Consume State\r\n\r\n```tsx\r\nimport { useArc } from '@buildincredibles/arc'\r\n\r\nconst Component = () => {\r\n  const { tier, stable, metrics } = useArc()\r\n\r\n  if (!stable) return null\r\n\r\n  if (tier === 'low') {\r\n    return <LightVersion />\r\n  }\r\n\r\n  return <FullVersion />\r\n}\r\n```\r\n\r\n---\r\n\r\n## Manual Override\r\n\r\nARC supports forcing a tier.\r\n\r\nUseful for:\r\n\r\n- Testing\r\n- QA\r\n- Performance debugging\r\n- Demo modes\r\n\r\n### Force Tier\r\n\r\n```ts\r\nimport { arc } from '@buildincredibles/arc'\r\n\r\narc.overrideTier('low')\r\n```\r\n\r\nThis immediately recalculates state with the forced tier.\r\n\r\n---\r\n\r\n### Reset Override\r\n\r\n```ts\r\narc.resetOverride()\r\n```\r\n\r\nReturns control to automatic tier calculation.\r\n\r\n---\r\n\r\n## Custom Engine (Optional)\r\n\r\nYou may create your own engine instance:\r\n\r\n```ts\r\nimport { ArcEngine } from '@buildincredibles/arc'\r\n\r\nconst engine = new ArcEngine(3000) // 3-second probe\r\n```\r\n\r\nDefault probe duration: `2000ms`.\r\n\r\n---\r\n\r\n## SSR Behavior\r\n\r\nARC checks for `window` before starting.\r\n\r\nProbing only runs in the browser.\r\nSafe for SSR environments.\r\n\r\n---\r\n\r\n## Design Guarantees\r\n\r\nARC:\r\n\r\n- Does not modify animations\r\n- Does not patch browser APIs\r\n- Does not force downgrades\r\n- Does not interfere with components\r\n\r\nIf a component does not consume `useArc()`, ARC has zero effect on it.\r\n\r\n---\r\n\r\n## Bundle Size\r\n\r\n- ~3 KB (ESM build)\r\n- No runtime dependencies\r\n- React as peer dependency only\r\n\r\n---\r\n\r\n## Intended Use Cases\r\n\r\n- Conditional animation complexity\r\n- Adaptive particle systems\r\n- Selective WebGL rendering\r\n- Dynamic blur/shadow intensity\r\n- Performance-aware feature toggling\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions are welcome.\r\n\r\nIf you would like to improve ARC:\r\n\r\n1. Fork the repository\r\n2. Create a new branch\r\n3. Make your changes with clear commit messages\r\n4. Ensure TypeScript types remain strict and consistent\r\n5. Open a pull request with a clear explanation of the improvement\r\n\r\nWhen contributing:\r\n\r\n- Keep the engine lightweight\r\n- Avoid adding runtime dependencies\r\n- Maintain strong type safety\r\n- Preserve SSR safety\r\n- Do not introduce automatic UI side-effects\r\n\r\nBug reports and feature suggestions can be opened as issues.\r\n\r\n---\r\n\r\n## Roadmap\r\n\r\nPotential future improvements:\r\n\r\n- Configurable tier thresholds\r\n- Optional continuous monitoring mode\r\n- Devtools integration\r\n- Visual performance dashboard\r\n- Non-React adapter layer\r\n\r\nARC is intentionally minimal. Any addition must justify its impact on size and complexity.\r\n\r\n---\r\n\r\n## Versioning\r\n\r\nARC follows semantic versioning:\r\n\r\n- **MAJOR** — Breaking API changes\r\n- **MINOR** — New features (non-breaking)\r\n- **PATCH** — Fixes and internal improvements\r\n\r\n---\r\n\r\n## Support\r\n\r\nIf you are using ARC in production and need guidance, integration help, or custom performance architecture consulting, you may contact:\r\n\r\nBuild Incredibles  \r\nhttps://buildincredibles.com\r\n\r\n---\r\n\r\n## Repository\r\n\r\nGitHub Organization:  \r\nhttps://github.com/buildincredibles\r\n\r\nARC Repository:  \r\nhttps://github.com/buildincredibles/arc\r\n\r\nIssues and feature requests should be opened in the repository.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT\r\n\r\n---\r\n\r\n## Maintained By\r\n\r\nBuild Incredibles  \r\nhttps://buildincredibles.com  \r\nhttps://github.com/buildincredibles\r\n","readmeFilename":"README.md","_rev":"1-675fcaec23664d6206b5c4a92a6581d5"}