open-grid 1.2.1 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (258) hide show
  1. package/CHANGELOG.md +388 -365
  2. package/dist/{OpenGrid-0r_543Kj.cjs → OpenGrid-B7m7ei7f.cjs} +1222 -1029
  3. package/dist/{OpenGrid-HmhGVC2V.js → OpenGrid-CeUdO_fM.js} +1613 -1418
  4. package/dist/index-CeJ-0-80.cjs +260 -0
  5. package/dist/index-DnarQ4eR.js +266 -0
  6. package/dist/index-DrCPRuYi.js +548 -0
  7. package/dist/index-JjfWY3Bt.cjs +520 -0
  8. package/dist/open-grid-base.css +12 -1
  9. package/dist/open-grid-react.cjs +1 -1
  10. package/dist/open-grid-react.js +1 -1
  11. package/dist/open-grid-vue.cjs +7 -7
  12. package/dist/open-grid-vue.js +2 -2
  13. package/dist/open-grid.cjs +1 -1
  14. package/dist/open-grid.js +2 -2
  15. package/dist/types/bench/perf.d.ts +14 -8
  16. package/dist/types/core/AppearanceResolver.d.ts +98 -11
  17. package/dist/types/core/CFRenderBridge.d.ts +13 -0
  18. package/dist/types/core/CellTypeRegistry.d.ts +24 -0
  19. package/dist/types/core/ColumnLayout.d.ts +100 -2
  20. package/dist/types/core/CrossGridMapper.d.ts +43 -5
  21. package/dist/types/core/DataLayer.d.ts +210 -15
  22. package/dist/types/core/DragVisuals.d.ts +33 -4
  23. package/dist/types/core/EventEmitter.d.ts +54 -0
  24. package/dist/types/core/FilterSelect.d.ts +26 -5
  25. package/dist/types/core/FormulaEngine.d.ts +15 -4
  26. package/dist/types/core/GridRenderer.d.ts +143 -10
  27. package/dist/types/core/GridShuttle.d.ts +26 -10
  28. package/dist/types/core/GroupEngine.d.ts +68 -10
  29. package/dist/types/core/IconRegistry.d.ts +31 -13
  30. package/dist/types/core/MathUtils.d.ts +58 -5
  31. package/dist/types/core/MergeEngine.d.ts +45 -10
  32. package/dist/types/core/OGDecimal.d.ts +144 -13
  33. package/dist/types/core/OpenGrid.d.ts +401 -122
  34. package/dist/types/core/OrgChart.d.ts +32 -11
  35. package/dist/types/core/PivotEngine.d.ts +37 -0
  36. package/dist/types/core/RowDragDrop.d.ts +52 -6
  37. package/dist/types/core/SkinRegistry.d.ts +86 -19
  38. package/dist/types/core/TreeEngine.d.ts +60 -6
  39. package/dist/types/core/VirtualScroll.d.ts +64 -0
  40. package/dist/types/core/XmlConverter.d.ts +40 -0
  41. package/dist/types/core/a11y/AccessibilityAdapter.d.ts +103 -0
  42. package/dist/types/core/a11y/AriaIntent.d.ts +34 -0
  43. package/dist/types/core/a11y/KeyboardInteractionModel.d.ts +64 -0
  44. package/dist/types/core/a11y/LiveRegionController.d.ts +89 -0
  45. package/dist/types/core/a11y/OverlayStack.d.ts +36 -0
  46. package/dist/types/core/a11y/VisualEquivRegistry.d.ts +37 -0
  47. package/dist/types/core/a11y/index.d.ts +13 -0
  48. package/dist/types/core/a11y/ports.d.ts +24 -0
  49. package/dist/types/core/appearance/Appearance.d.ts +68 -0
  50. package/dist/types/core/appearance/AppearanceAxis.d.ts +94 -0
  51. package/dist/types/core/appearance/AppearanceComposer.d.ts +45 -0
  52. package/dist/types/core/appearance/AppearanceProvider.d.ts +50 -0
  53. package/dist/types/core/appearance/AppearanceView.d.ts +51 -0
  54. package/dist/types/core/appearance/DensityRegistry.d.ts +36 -0
  55. package/dist/types/core/appearance/ResolvedAppearanceSnapshot.d.ts +84 -0
  56. package/dist/types/core/appearance/TextureRegistry.d.ts +32 -0
  57. package/dist/types/core/appearance/ThemeMetaRegistry.d.ts +67 -0
  58. package/dist/types/core/appearance/axisAdapters.d.ts +37 -0
  59. package/dist/types/core/appearance/defaults.d.ts +10 -0
  60. package/dist/types/core/appearance/index.d.ts +20 -0
  61. package/dist/types/core/appearance/tokenCatalog.d.ts +30 -0
  62. package/dist/types/core/cf/CFEngine.d.ts +56 -0
  63. package/dist/types/core/cf/CFEvaluator.d.ts +24 -0
  64. package/dist/types/core/cf/CFRule.d.ts +127 -0
  65. package/dist/types/core/cf/ColorScale.d.ts +49 -0
  66. package/dist/types/core/cf/InkResolver.d.ts +33 -0
  67. package/dist/types/core/cf/appearance.d.ts +20 -0
  68. package/dist/types/core/cf/encoders.d.ts +61 -0
  69. package/dist/types/core/cf/eval-types.d.ts +93 -0
  70. package/dist/types/core/cf/index.d.ts +21 -0
  71. package/dist/types/core/cf/lineage.d.ts +32 -0
  72. package/dist/types/core/cf/predicates.d.ts +27 -0
  73. package/dist/types/core/cf/serialize.d.ts +46 -0
  74. package/dist/types/core/chart/CanvasAdapter.d.ts +50 -1
  75. package/dist/types/core/chart/DataExtractor.d.ts +53 -12
  76. package/dist/types/core/chart/a11y.d.ts +22 -0
  77. package/dist/types/core/chart/chart-type-registry.d.ts +53 -0
  78. package/dist/types/core/chart/downsample-report.d.ts +36 -0
  79. package/dist/types/core/chart/downsample.d.ts +26 -1
  80. package/dist/types/core/chart/engine/ChartEngineRegistry.d.ts +52 -0
  81. package/dist/types/core/chart/geometry.d.ts +96 -0
  82. package/dist/types/core/chart/hittest.d.ts +21 -3
  83. package/dist/types/core/chart/palette.d.ts +96 -12
  84. package/dist/types/core/chart/parity.d.ts +12 -0
  85. package/dist/types/core/chart/provenance.d.ts +47 -0
  86. package/dist/types/core/chart/scales.d.ts +28 -1
  87. package/dist/types/core/chart/scene.d.ts +102 -0
  88. package/dist/types/core/chart/server.d.ts +36 -0
  89. package/dist/types/core/chart/surfaces/CanvasSurface.d.ts +48 -0
  90. package/dist/types/core/chart/surfaces/ServerRasterSurface.d.ts +26 -0
  91. package/dist/types/core/chart/surfaces/SvgSurface.d.ts +24 -0
  92. package/dist/types/core/chart/surfaces/pattern-overlay.d.ts +24 -0
  93. package/dist/types/core/chart/types.d.ts +102 -21
  94. package/dist/types/core/command/CommandBus.d.ts +51 -0
  95. package/dist/types/core/command/CommandRegistry.d.ts +43 -0
  96. package/dist/types/core/command/CommandStack.d.ts +38 -0
  97. package/dist/types/core/command/ICommand.d.ts +110 -0
  98. package/dist/types/core/command/commands/CellWriteCommand.d.ts +32 -0
  99. package/dist/types/core/command/commands/CompositeCommand.d.ts +17 -0
  100. package/dist/types/core/command/commands/RowCommands.d.ts +39 -0
  101. package/dist/types/core/command/index.d.ts +9 -0
  102. package/dist/types/core/command/support.d.ts +51 -0
  103. package/dist/types/core/coordinate/ColumnMetrics.d.ts +30 -0
  104. package/dist/types/core/coordinate/CoordinateKernel.d.ts +88 -0
  105. package/dist/types/core/coordinate/FrozenPanes.d.ts +29 -0
  106. package/dist/types/core/coordinate/MergeSourceAdapter.d.ts +18 -0
  107. package/dist/types/core/coordinate/NodeBudget.d.ts +33 -0
  108. package/dist/types/core/coordinate/ResizeGovernor.d.ts +50 -0
  109. package/dist/types/core/coordinate/RowMetrics.d.ts +37 -0
  110. package/dist/types/core/coordinate/ViewPermutation.d.ts +23 -0
  111. package/dist/types/core/coordinate/index.d.ts +10 -0
  112. package/dist/types/core/coordinate/ports.d.ts +45 -0
  113. package/dist/types/core/coordinate/types.d.ts +76 -0
  114. package/dist/types/core/detail/DetailGlyph.d.ts +42 -7
  115. package/dist/types/core/detail/DetailSplice.d.ts +42 -11
  116. package/dist/types/core/detail/DetailState.d.ts +80 -11
  117. package/dist/types/core/detail/SubgridCache.d.ts +72 -10
  118. package/dist/types/core/detail/index.d.ts +8 -0
  119. package/dist/types/core/domain/AggregateResult.d.ts +54 -0
  120. package/dist/types/core/domain/CellAddress.d.ts +61 -0
  121. package/dist/types/core/domain/CellValueAccess.d.ts +29 -0
  122. package/dist/types/core/domain/Delta.d.ts +37 -0
  123. package/dist/types/core/domain/DomainValue.d.ts +80 -0
  124. package/dist/types/core/domain/Missing.d.ts +65 -0
  125. package/dist/types/core/domain/Money.d.ts +42 -0
  126. package/dist/types/core/domain/NormalizationBasis.d.ts +47 -0
  127. package/dist/types/core/domain/Plain.d.ts +45 -0
  128. package/dist/types/core/domain/Quantity.d.ts +32 -0
  129. package/dist/types/core/domain/Ratios.d.ts +100 -0
  130. package/dist/types/core/domain/ThresholdSet.d.ts +46 -0
  131. package/dist/types/core/domain/ValueType.d.ts +71 -0
  132. package/dist/types/core/domain/rounding.d.ts +25 -0
  133. package/dist/types/core/domain/strategies.d.ts +38 -0
  134. package/dist/types/core/editors/DateEditor.d.ts +18 -0
  135. package/dist/types/core/editors/SelectEditor.d.ts +29 -0
  136. package/dist/types/core/export/ChannelRegistry.d.ts +18 -0
  137. package/dist/types/core/export/ExportManifest.d.ts +13 -0
  138. package/dist/types/core/export/GridArtifactSource.d.ts +62 -0
  139. package/dist/types/core/export/Provenance.d.ts +34 -0
  140. package/dist/types/core/export/StreamPump.d.ts +28 -0
  141. package/dist/types/core/export/channels/CsvChannel.d.ts +20 -0
  142. package/dist/types/core/export/channels/JsonChannel.d.ts +18 -0
  143. package/dist/types/core/export/channels/XlsxChannel.d.ts +53 -0
  144. package/dist/types/core/export/channels/XmlChannel.d.ts +21 -0
  145. package/dist/types/core/export/channels/capabilities.d.ts +13 -0
  146. package/dist/types/core/export/index.d.ts +24 -0
  147. package/dist/types/core/export/print/OutputChannelAdapter.d.ts +61 -0
  148. package/dist/types/core/export/print/Paginator.d.ts +48 -0
  149. package/dist/types/core/export/print/PrintRenderTarget.d.ts +36 -0
  150. package/dist/types/core/export/sinks.d.ts +40 -0
  151. package/dist/types/core/export/types.d.ts +211 -0
  152. package/dist/types/core/extension/DeprecationManager.d.ts +42 -0
  153. package/dist/types/core/extension/IExtension.d.ts +90 -0
  154. package/dist/types/core/extension/Registry.d.ts +142 -0
  155. package/dist/types/core/extension/SlotRegistry.d.ts +46 -0
  156. package/dist/types/core/extension/adapters.d.ts +44 -0
  157. package/dist/types/core/extension/conformance.d.ts +47 -0
  158. package/dist/types/core/extension/index.d.ts +16 -0
  159. package/dist/types/core/extension/registries.d.ts +31 -0
  160. package/dist/types/core/extension/reserved.d.ts +10 -0
  161. package/dist/types/core/format/DisplayFormatter.d.ts +47 -0
  162. package/dist/types/core/format/FormatCache.d.ts +20 -0
  163. package/dist/types/core/format/FormatterRegistry.d.ts +22 -0
  164. package/dist/types/core/format/grammar/AstRenderer.d.ts +10 -0
  165. package/dist/types/core/format/grammar/FormatCompiler.d.ts +16 -0
  166. package/dist/types/core/format/index.d.ts +55 -0
  167. package/dist/types/core/format/pipeline/DomainTypeResolver.d.ts +8 -0
  168. package/dist/types/core/format/pipeline/LocaleFormat.d.ts +11 -0
  169. package/dist/types/core/format/pipeline/ValueInterpreter.d.ts +8 -0
  170. package/dist/types/core/format/policy/MaskPolicy.d.ts +8 -0
  171. package/dist/types/core/format/policy/NegativePolicy.d.ts +12 -0
  172. package/dist/types/core/format/policy/NullPolicy.d.ts +10 -0
  173. package/dist/types/core/format/policy/TruncatePolicy.d.ts +11 -0
  174. package/dist/types/core/format/types.d.ts +292 -0
  175. package/dist/types/core/formula/CalcCacheStore.d.ts +89 -0
  176. package/dist/types/core/formula/CalcProvenance.d.ts +44 -0
  177. package/dist/types/core/formula/CalcService.d.ts +137 -0
  178. package/dist/types/core/formula/CyclePathReporter.d.ts +28 -0
  179. package/dist/types/core/formula/FormulaEvaluator.d.ts +35 -1
  180. package/dist/types/core/formula/FormulaGraph.d.ts +84 -7
  181. package/dist/types/core/formula/FormulaParser.d.ts +9 -0
  182. package/dist/types/core/formula/FormulaStore.d.ts +63 -1
  183. package/dist/types/core/formula/FunctionRegistry.d.ts +138 -0
  184. package/dist/types/core/formula/Generation.d.ts +86 -0
  185. package/dist/types/core/formula/RecalcCoordinator.d.ts +151 -9
  186. package/dist/types/core/formula/ReferenceRewriter.d.ts +81 -0
  187. package/dist/types/core/formula/functions/essential.d.ts +3 -0
  188. package/dist/types/core/formula/functions/extended/index.d.ts +10 -0
  189. package/dist/types/core/formula/normalizeRefs.d.ts +34 -3
  190. package/dist/types/core/formula/numericLiteral.d.ts +11 -1
  191. package/dist/types/core/formula/serializeFormula.d.ts +10 -1
  192. package/dist/types/core/host/CapabilityRegistry.d.ts +61 -0
  193. package/dist/types/core/host/GridHostDriver.d.ts +27 -0
  194. package/dist/types/core/host/GridHostPort.d.ts +37 -0
  195. package/dist/types/core/host/SliceOwnershipGuard.d.ts +27 -0
  196. package/dist/types/core/host/archCheck.d.ts +26 -0
  197. package/dist/types/core/host/index.d.ts +6 -0
  198. package/dist/types/core/host/reconcile.d.ts +22 -0
  199. package/dist/types/core/i18n/LocaleContext.d.ts +40 -0
  200. package/dist/types/core/i18n/LocaleRegistry.d.ts +0 -0
  201. package/dist/types/core/i18n/types.d.ts +67 -11
  202. package/dist/types/core/icons/bootstrap-icons.d.ts +4 -2
  203. package/dist/types/core/quality/ContrastAuditor.d.ts +64 -0
  204. package/dist/types/core/quality/DeterminismKernel.d.ts +68 -0
  205. package/dist/types/core/quality/PerfBaseline.d.ts +23 -0
  206. package/dist/types/core/quality/PerfSpec.d.ts +95 -0
  207. package/dist/types/core/quality/RealBrowserGate.d.ts +69 -0
  208. package/dist/types/core/quality/RegressionJudge.d.ts +35 -0
  209. package/dist/types/core/quality/ReleaseGate.d.ts +94 -0
  210. package/dist/types/core/quality/VisualRegression.d.ts +74 -0
  211. package/dist/types/core/quality/hooks.d.ts +53 -0
  212. package/dist/types/core/quality/index.d.ts +20 -0
  213. package/dist/types/core/quality/pixelMetrics.d.ts +24 -0
  214. package/dist/types/core/range/ClipboardCodec.d.ts +46 -4
  215. package/dist/types/core/range/FillEngine.d.ts +69 -9
  216. package/dist/types/core/range/RangeModel.d.ts +100 -13
  217. package/dist/types/core/range/types.d.ts +27 -11
  218. package/dist/types/core/realtime/BackpressureScheduler.d.ts +0 -0
  219. package/dist/types/core/realtime/FreshnessClock.d.ts +34 -0
  220. package/dist/types/core/realtime/IRealtimeSource.d.ts +82 -0
  221. package/dist/types/core/realtime/LiveStateGuard.d.ts +23 -0
  222. package/dist/types/core/realtime/PollingSource.d.ts +42 -0
  223. package/dist/types/core/realtime/RealtimeController.d.ts +54 -0
  224. package/dist/types/core/realtime/RtAnnouncePolicy.d.ts +53 -0
  225. package/dist/types/core/realtime/RtApplyCommand.d.ts +29 -0
  226. package/dist/types/core/realtime/RtChartTargetTrigger.d.ts +26 -0
  227. package/dist/types/core/realtime/StreamingSource.d.ts +47 -0
  228. package/dist/types/core/realtime/backoff.d.ts +12 -0
  229. package/dist/types/core/realtime/index.d.ts +13 -0
  230. package/dist/types/core/realtime/ports.d.ts +80 -0
  231. package/dist/types/core/render/CellApplier.d.ts +18 -0
  232. package/dist/types/core/render/CellErrorBoundary.d.ts +65 -0
  233. package/dist/types/core/render/CellPipeline.d.ts +39 -0
  234. package/dist/types/core/render/CellRenderRequest.d.ts +209 -0
  235. package/dist/types/core/render/CellStageRegistry.d.ts +53 -0
  236. package/dist/types/core/render/OverlayCompositor.d.ts +38 -0
  237. package/dist/types/core/render/RenderBudget.d.ts +67 -0
  238. package/dist/types/core/render/contrast.d.ts +33 -0
  239. package/dist/types/core/render/index.d.ts +35 -0
  240. package/dist/types/core/render/stages/BackgroundStage.d.ts +14 -0
  241. package/dist/types/core/render/stages/DecoratorStage.d.ts +12 -0
  242. package/dist/types/core/render/stages/OverlayStage.d.ts +12 -0
  243. package/dist/types/core/render/stages/ValueRendererStage.d.ts +15 -0
  244. package/dist/types/core/render/stages/index.d.ts +14 -0
  245. package/dist/types/core/state/AutosaveController.d.ts +63 -0
  246. package/dist/types/core/state/IStatePersistence.d.ts +59 -0
  247. package/dist/types/core/state/MultiTabGuard.d.ts +33 -0
  248. package/dist/types/core/state/SchemaMigrator.d.ts +33 -0
  249. package/dist/types/core/state/SemVerPolicy.d.ts +39 -0
  250. package/dist/types/core/state/StateCodec.d.ts +75 -0
  251. package/dist/types/core/state/index.d.ts +6 -0
  252. package/dist/types/core/types.d.ts +511 -226
  253. package/dist/types/react/OpenGrid.d.ts +54 -0
  254. package/dist/types/react/index.d.ts +5 -0
  255. package/dist/types/realtime/index.d.ts +1 -0
  256. package/dist/types/vue/index.d.ts +5 -0
  257. package/dist/types/vue/types.d.ts +35 -0
  258. package/package.json +112 -111
@@ -0,0 +1,34 @@
1
+ export type FreshnessState = 'fresh' | 'stale';
2
+ export interface FreshnessSnapshot {
3
+ readonly state: FreshnessState;
4
+ readonly ageMs: number;
5
+ readonly lastReceivedAt?: number;
6
+ }
7
+ export interface FreshnessConfig {
8
+ readonly staleAfterMs: number;
9
+ readonly now?: () => number;
10
+ }
11
+ /**
12
+ * 신선도 시효 파생. markReceived 로 시계 리셋, compute 로 현재 파생값, onChange 로 전이 통지.
13
+ * / Freshness derivation: markReceived resets, compute derives, onChange notifies transitions.
14
+ */
15
+ export declare class FreshnessClock {
16
+ private readonly _staleAfterMs;
17
+ private readonly _now;
18
+ private _lastReceivedAt;
19
+ private _lastState;
20
+ private readonly _listeners;
21
+ constructor(cfg: FreshnessConfig);
22
+ /** 성공 수신 기록 — 시계 리셋(fresh 로 전이 가능). / Record a successful receive. */
23
+ markReceived(at: number): void;
24
+ /** 현재 신선도 상태 파생값. / Current derived freshness. */
25
+ compute(): FreshnessSnapshot;
26
+ /**
27
+ * 신선도 전이 재평가 트리거(시간 경과는 외부 tick 이 호출 — RT 는 전역 타이머 미소유).
28
+ * 배지가 주기 폴하거나 연결/수신 이벤트 시 호출. 전이가 있으면 onChange 발화.
29
+ * / Re-evaluate freshness (driven by an external tick — RT owns no global timer).
30
+ */
31
+ tick(): FreshnessSnapshot;
32
+ private _emitIfChanged;
33
+ onChange(l: (f: FreshnessSnapshot) => void): () => void;
34
+ }
@@ -0,0 +1,82 @@
1
+ /** 서버 페이로드 — 두 형태(전체 스냅샷 / 부분 델타). 전송 프로토콜 무관(코어가 소비하는 정규형). */
2
+ export type RtPayload<T> = SnapshotPayload<T> | DeltaPayload<T>;
3
+ /** 전체 스냅샷: 데이터셋 통째 교체. seq/serverTime 은 신선도·순서 판정용. */
4
+ export interface SnapshotPayload<T> {
5
+ readonly kind: 'snapshot';
6
+ readonly rows: readonly T[];
7
+ /** 단조 증가 시퀀스(순서 역전 방지). / Monotonic sequence. */
8
+ readonly seq: number;
9
+ /** 서버 발신 epoch(ms) — 신선도 계산 입력. / Server-emit epoch(ms). */
10
+ readonly serverTime?: number;
11
+ }
12
+ /** 부분 델타: 행/셀 단위 변경 집합(전체 리로드 없이 증분 적용). */
13
+ export interface DeltaPayload<T> {
14
+ readonly kind: 'delta';
15
+ readonly seq: number;
16
+ readonly serverTime?: number;
17
+ /** 행 upsert(존재 시 병합, 없으면 추가) — rowId(안정키) 기준. */
18
+ readonly upserts?: ReadonlyArray<{
19
+ readonly rowId: string;
20
+ readonly row: Partial<T>;
21
+ }>;
22
+ /** 셀 단위 패치 — 최소 단위 변경(영향 셀만). */
23
+ readonly cells?: ReadonlyArray<{
24
+ readonly rowId: string;
25
+ readonly field: keyof T & string;
26
+ readonly value: unknown;
27
+ }>;
28
+ /** 행 제거 — rowId 기준. */
29
+ readonly removes?: readonly string[];
30
+ }
31
+ /** 연결 상태 전이 상수. / Connection-status transition constants. */
32
+ export type ConnectionStatus = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'error';
33
+ /** 무언 삼킴 금지 — 오류는 상태에 남는다. / Never swallowed — errors persist in state. */
34
+ export interface RtError {
35
+ readonly code: string;
36
+ readonly message: string;
37
+ readonly at: number;
38
+ }
39
+ /**
40
+ * 연결 상태 값객체(불변). stale 은 신선도 시계(FreshnessClock)에서 파생 — 여기엔 원자 연결 사실만.
41
+ * / Immutable connection-state value object; staleness is derived by FreshnessClock.
42
+ */
43
+ export interface ConnectionState {
44
+ readonly status: ConnectionStatus;
45
+ /** 마지막 성공 수신 epoch(ms). / Last successful receive epoch(ms). */
46
+ readonly lastReceivedAt?: number;
47
+ /** 무언 삼킴 금지 — 마지막 오류 노출. / Last error, surfaced (never swallowed). */
48
+ readonly lastError?: RtError;
49
+ /** 현재 backoff 회차(0=정상). / Current backoff attempt (0 = healthy). */
50
+ readonly retryAttempt: number;
51
+ /** 다음 재연결 예정 시각. / Next scheduled reconnect time. */
52
+ readonly nextRetryAt?: number;
53
+ }
54
+ /** 지수 backoff(+jitter) 정책 — 재연결. 상한/최대 시도 후 error 표면화(무언 삼킴 0). */
55
+ export interface BackoffPolicy {
56
+ readonly baseMs: number;
57
+ readonly factor: number;
58
+ readonly maxMs: number;
59
+ /** 미지정=무한(단, 상태는 항상 reconnecting 노출). / Absent = infinite. */
60
+ readonly maxAttempts?: number;
61
+ readonly jitter?: boolean;
62
+ }
63
+ /**
64
+ * 실시간 데이터 소스 — **단일 push 인터페이스**. 코어는 이것만 안다(DI).
65
+ * 어댑터(폴링/스트리밍/제3자)는 이 계약만 구현. 코어↔전송 완전 분리(REQ-RT-801).
66
+ * 불변식: onData 는 seq 단조 증가 순으로만 관측자에게 전달(역전은 소스가 삼키지 말고 드롭+경고).
67
+ * / Single push interface; the core knows only this (transport injected via DI).
68
+ */
69
+ export interface IRealtimeSource<T> {
70
+ /** 수신 시작. 연결 수립까지 포함(스트리밍) 또는 첫 폴 예약(폴링). */
71
+ start(): void;
72
+ /** 수신 중단. 타이머/소켓 정리(멱등). */
73
+ stop(): void;
74
+ /** 정규화된 페이로드 1건 도착. 다중 구독 가능. 반환=해제 함수. */
75
+ onData(listener: (payload: RtPayload<T>) => void): () => void;
76
+ /** 연결 상태 전이 관측(연결/재연결/끊김/오류). 반환=해제 함수. */
77
+ onStatus(listener: (s: ConnectionState) => void): () => void;
78
+ /** 현재 연결 상태 스냅샷. */
79
+ readonly status: ConnectionState;
80
+ }
81
+ /** seq 단조성 판정(순수) — 역전/중복 드롭 근거. / Monotonic-seq guard (pure). */
82
+ export declare function isSeqNewer(prevSeq: number | undefined, incoming: number): boolean;
@@ -0,0 +1,23 @@
1
+ import { LiveStateSource, LiveUserState, RtCoords } from './ports.js';
2
+ import { AppliedDelta } from './RtAnnouncePolicy.js';
3
+ /** S-1 편집충돌 힌트 — 편집 중 셀이 서버 델타로 바뀜(UI 신선도 힌트용). / Edit-conflict hint. */
4
+ export interface EditConflict {
5
+ readonly rowId: string;
6
+ readonly field: string;
7
+ }
8
+ /**
9
+ * 상태 캡처/복원 어댑터. 실제 선택/스크롤/편집 서브시스템은 LiveStateSource 로 주입(신설 아님).
10
+ * / Capture/restore adapter; the real selection/scroll/edit subsystems are injected via LiveStateSource.
11
+ */
12
+ export declare class LiveStateGuard {
13
+ private readonly _src;
14
+ private readonly _coords;
15
+ private _lastConflicts;
16
+ constructor(src: LiveStateSource, coords: RtCoords);
17
+ /** 마지막 restore 의 편집충돌(S-1 힌트). / Edit conflicts from the last restore. */
18
+ get lastConflicts(): readonly EditConflict[];
19
+ /** 적용 전 스냅샷(rowId 앵커). / Pre-apply snapshot (rowId-anchored). */
20
+ capture(): LiveUserState;
21
+ /** 적용 후 오프셋 재정합. 인덱스가 아니라 rowId 로 복원. / Post-apply reconciliation, by rowId. */
22
+ restore(s: LiveUserState, applied: AppliedDelta): void;
23
+ }
@@ -0,0 +1,42 @@
1
+ import { BackoffPolicy, ConnectionState, IRealtimeSource, RtPayload } from './IRealtimeSource.js';
2
+ import { TimerScheduler } from './ports.js';
3
+ export interface PollingConfig<T> {
4
+ readonly intervalMs: number;
5
+ /** 사용자 제공 — 코어는 내부(HTTP 등)를 모른다. / User-provided; the core knows nothing inside. */
6
+ readonly fetcher: (ctx: {
7
+ since?: number;
8
+ signal: AbortSignal;
9
+ }) => Promise<RtPayload<T>>;
10
+ /** 폴 실패 재시도 정책. 미지정=고정 intervalMs 재시도. / Retry policy; default fixed interval. */
11
+ readonly backoff?: BackoffPolicy;
12
+ /** 지연 실행 주입(테스트 수동 시계). / Injected timer. */
13
+ readonly timer?: TimerScheduler;
14
+ readonly now?: () => number;
15
+ readonly random?: () => number;
16
+ }
17
+ /** 폴링 소스 — IRealtimeSource 구현. seq 정규화·상태 방출만 책임. / Polling source. */
18
+ export declare class PollingSource<T> implements IRealtimeSource<T> {
19
+ private readonly _cfg;
20
+ private readonly _timer;
21
+ private readonly _now;
22
+ private readonly _random;
23
+ private readonly _dataListeners;
24
+ private readonly _statusListeners;
25
+ private _state;
26
+ private _lastSeq;
27
+ private _since;
28
+ private _handle;
29
+ private _abort;
30
+ private _started;
31
+ constructor(cfg: PollingConfig<T>);
32
+ get status(): ConnectionState;
33
+ onData(listener: (p: RtPayload<T>) => void): () => void;
34
+ onStatus(listener: (s: ConnectionState) => void): () => void;
35
+ start(): void;
36
+ stop(): void;
37
+ private _scheduleNext;
38
+ private _poll;
39
+ private _onPayload;
40
+ private _onFailure;
41
+ private _transition;
42
+ }
@@ -0,0 +1,54 @@
1
+ import { ConnectionState, IRealtimeSource } from './IRealtimeSource.js';
2
+ import { FreshnessClock } from './FreshnessClock.js';
3
+ import { LiveStateGuard } from './LiveStateGuard.js';
4
+ import { RtAnnouncePolicy } from './RtAnnouncePolicy.js';
5
+ import { RtChartTargetTrigger } from './RtChartTargetTrigger.js';
6
+ import { FrameScheduler, RtCommandSink } from './ports.js';
7
+ export interface RealtimeControllerDeps<T> {
8
+ /** 단일 쓰기 이음새(DD-09 CommandBus 부분집합). RT 델타 = 비-undoable silent 커맨드. */
9
+ readonly sink: RtCommandSink<T>;
10
+ /** 사용자 상태 캡처/복원(전환 보존 계약 재사용). / State capture/restore. */
11
+ readonly stateGuard: LiveStateGuard;
12
+ /** 신선도 시계(연결/stale 표기). / Freshness clock. */
13
+ readonly freshness: FreshnessClock;
14
+ /** 실시간 접근성 게이트(백그라운드 SR 공지 정책). / A11y announce gate. */
15
+ readonly announce: RtAnnouncePolicy;
16
+ /** 프레임 예산 스케줄러 주입(rAF 전역 미참조). 미지정=기본 rAF/폴백. */
17
+ readonly scheduleFrame?: FrameScheduler;
18
+ /** 프레임당 최대 적용 셀 수(백프레셔). / Max cells applied per frame. */
19
+ readonly maxBatchPerFrame?: number;
20
+ /** 차트 갱신 신호(영향 시리즈만). DD-06 위임. / Chart dirty trigger. */
21
+ readonly chart?: RtChartTargetTrigger;
22
+ /** 전체 스냅샷 적용 훅(통합 TODO: DataLayer.setData 배선). 미지정=경고 후 스킵. */
23
+ readonly applySnapshot?: (rows: readonly T[]) => void;
24
+ readonly now?: () => number;
25
+ }
26
+ /**
27
+ * RT 서브시스템 조립 루트. 소스 1개를 그리드/차트에 배선. OpenGrid 가 소유·주입(통합 TODO).
28
+ * / Assembly root wiring one source to the grid/chart; owned & injected by OpenGrid.
29
+ */
30
+ export declare class RealtimeController<T> {
31
+ private readonly _source;
32
+ private readonly _deps;
33
+ private readonly _scheduler;
34
+ private readonly _now;
35
+ private readonly _statusListeners;
36
+ private _offData;
37
+ private _offStatus;
38
+ private _connection;
39
+ private _attached;
40
+ constructor(source: IRealtimeSource<T>, deps: RealtimeControllerDeps<T>);
41
+ /** 소스 start + onData/onStatus 구독 배선. 멱등. / Wire subscriptions + start. Idempotent. */
42
+ attach(): void;
43
+ /** 구독 해제 + source.stop() + scheduler.dispose(). 멱등. / Teardown. Idempotent. */
44
+ detach(): void;
45
+ /** 연결 상태 스냅샷(UI 배지용). / Connection snapshot (for UI badge). */
46
+ get connection(): ConnectionState;
47
+ /** 백프레셔 계측(폭주 0 검증). / Backpressure stats. */
48
+ get backpressureStats(): import('./BackpressureScheduler.js').BackpressureStats;
49
+ /** 연결 상태 관측(배지 배선). / Observe connection transitions. */
50
+ onConnection(l: (s: ConnectionState) => void): () => void;
51
+ private _onData;
52
+ private _onStatus;
53
+ private _applyBatch;
54
+ }
@@ -0,0 +1,53 @@
1
+ import { TimerScheduler } from './ports.js';
2
+ /** commit 결과 요약(복원 오프셋·SR 규모 요약 입력). / Applied-delta summary. */
3
+ export interface AppliedDelta {
4
+ readonly changedCells: readonly {
5
+ rowId: string;
6
+ field: string;
7
+ }[];
8
+ readonly insertedRowIds: readonly string[];
9
+ readonly removedRowIds: readonly string[];
10
+ /** 실시간 = 항상 백그라운드. / Realtime = always background. */
11
+ readonly userInitiated: false;
12
+ }
13
+ /** DD-12 로 넘어가는 요약 메시지 형태. / Summary message handed to DD-12. */
14
+ export interface RtAnnounceSummary {
15
+ readonly kind: 'background-update' | 'connection';
16
+ readonly changedCount: number;
17
+ readonly rowCount: number;
18
+ /** i18n 키 'rt.backgroundUpdate' / 'rt.connection'. / i18n label. */
19
+ readonly label: 'background' | 'connection';
20
+ /** 편집/포커스 방해 금지 불변식. / Never interrupts focus. */
21
+ readonly interruptsFocus: false;
22
+ /** 연결 공지 시 상태 텍스트(정직 노출). / Connection status text. */
23
+ readonly connectionStatus?: string;
24
+ }
25
+ export interface RtAnnouncePolicyConfig {
26
+ /** DD-12 aria-live 로 넘기는 콜백. / Handoff to DD-12 aria-live. */
27
+ readonly announce: (summary: RtAnnounceSummary) => void;
28
+ /** 디바운스 윈도우(ms). 기본 500. / Debounce window(ms). */
29
+ readonly debounceMs?: number;
30
+ /** 지연 실행 주입(테스트 결정론). / Injected timer. */
31
+ readonly schedule?: TimerScheduler;
32
+ }
33
+ /**
34
+ * 백그라운드 값 변화·연결 상태를 디바운스 병합해 규모 요약으로 DD-12 에 넘긴다.
35
+ * 연결 공지(끊김/재연결/오류)는 디바운스하지 않고 즉시(정직·지연 금지).
36
+ * / Debounce-merges background value changes into a magnitude summary; connection is immediate.
37
+ */
38
+ export declare class RtAnnouncePolicy {
39
+ private readonly _announce;
40
+ private readonly _debounceMs;
41
+ private readonly _schedule;
42
+ private _pendingCells;
43
+ private _pendingRows;
44
+ private _timer;
45
+ constructor(cfg: RtAnnouncePolicyConfig);
46
+ /** 백그라운드 갱신 — 규모 누적 후 디바운스 flush. / Accumulate then debounce-flush. */
47
+ onBackgroundChange(applied: AppliedDelta): void;
48
+ private _arm;
49
+ private _flush;
50
+ /** 연결 전이 공지 — 즉시(정직, 디바운스 없음). / Connection transition — immediate. */
51
+ onConnection(statusText: string): void;
52
+ dispose(): void;
53
+ }
@@ -0,0 +1,29 @@
1
+ import { ICommand, ICommandCtx, CommandDTO, CommandFootprint } from '../command/ICommand.js';
2
+ import { NormalizedBatch } from './BackpressureScheduler.js';
3
+ import { AppliedDelta } from './RtAnnouncePolicy.js';
4
+ /**
5
+ * 정규화 배치 1프레임분을 do 시 기존 초크포인트로 적용. 백그라운드(userInitiated=false)·silent.
6
+ * undo 계약은 완결성 위해 구현하나(포획 inverse 복원), RT 경로는 dispatchSilent 로 스택 미적재.
7
+ * / Applies one normalized frame via the existing chokepoint; silent/background, but a well-formed
8
+ * ICommand (undo restores captured inverse). RT dispatches silently (never pushed to the undo stack).
9
+ */
10
+ export declare class RtApplyCommand<T> implements ICommand<T> {
11
+ readonly spi: "command";
12
+ readonly kind = "rt.apply";
13
+ readonly label = "rt.backgroundUpdate";
14
+ readonly footprint: CommandFootprint;
15
+ private readonly _batch;
16
+ private _at;
17
+ private _cellInverse;
18
+ private _insertedRowIds;
19
+ private _removedInverse;
20
+ private _applied;
21
+ constructor(batch: NormalizedBatch<T>);
22
+ /** do 이후 적용 요약(상태 복원·SR 규모 요약 입력). / Applied summary after do. */
23
+ get appliedDelta(): AppliedDelta | undefined;
24
+ do(ctx: ICommandCtx<T>): void;
25
+ /** 완결성용 역적용(RT silent 경로는 호출 안 함). / Inverse (unused on the RT silent path). */
26
+ undo(ctx: ICommandCtx<T>): void;
27
+ serialize(): CommandDTO;
28
+ private static _footprintOf;
29
+ }
@@ -0,0 +1,26 @@
1
+ /** DD-06 소유(재선언 금지) — 통합 시 '../chart/scene' 에서 import. / Owned by DD-06. */
2
+ export type RenderTargetKind = 'canvas' | 'svg' | 'server';
3
+ /**
4
+ * RT 차트 타깃 트리거. target=서버면 DD-06 renderChartServer 로 위임(RT 재구현 0).
5
+ * markDirty 로 영향 시리즈(rowIds)만 재렌더 신호. 실제 scene 조립·paint·직렬화·파리티는 DD-06.
6
+ * / RT chart trigger: selection signal + live dirty only; actual render delegated to DD-06.
7
+ */
8
+ export interface RtChartTargetTrigger {
9
+ /** 공개 옵션(REQ-RT-804). 미지정=client 현행(하위호환). / Public option; default client. */
10
+ readonly target: RenderTargetKind;
11
+ /** 영향 시리즈만 재렌더 신호. 실제 렌더 실행은 DD-06 위임. / Mark impacted series dirty. */
12
+ markDirty(rowIds: readonly string[]): void;
13
+ }
14
+ /**
15
+ * 기본 트리거 — dirty rowId 를 누적하고 drain 으로 배출(DD-06 배선 전 수집만).
16
+ * / Default trigger: accumulates dirty rowIds and drains them (collect-only until DD-06 wired).
17
+ */
18
+ export declare class DefaultRtChartTargetTrigger implements RtChartTargetTrigger {
19
+ readonly target: RenderTargetKind;
20
+ private readonly _dirty;
21
+ private readonly _onDirty?;
22
+ constructor(target?: RenderTargetKind, onDirty?: (rowIds: readonly string[]) => void);
23
+ markDirty(rowIds: readonly string[]): void;
24
+ /** 누적 dirty rowId 배출(테스트/DD-06 배선용). / Drain accumulated dirty rowIds. */
25
+ drain(): string[];
26
+ }
@@ -0,0 +1,47 @@
1
+ import { BackoffPolicy, ConnectionState, IRealtimeSource, RtPayload } from './IRealtimeSource.js';
2
+ import { TimerScheduler } from './ports.js';
3
+ /** 전송 SPI — SSE/WebSocket/커스텀 프레이밍 교체(코어는 프레이밍 무지). / Transport SPI. */
4
+ export interface StreamTransport {
5
+ open(handlers: {
6
+ onMessage: (raw: string | ArrayBuffer) => void;
7
+ onOpen: () => void;
8
+ onClose: (why?: unknown) => void;
9
+ onError: (e: unknown) => void;
10
+ }): void;
11
+ close(): void;
12
+ }
13
+ export interface StreamingConfig<T> {
14
+ /** SSE/WebSocket 중 무엇이든 이 계약만 만족하면 됨. / Any transport satisfying the SPI. */
15
+ readonly transport: StreamTransport;
16
+ /** 원문 프레임 → 정규 페이로드(anti-corruption). null=무시할 프레임. / Decode; null = ignore frame. */
17
+ readonly decode: (raw: string | ArrayBuffer) => RtPayload<T> | null;
18
+ readonly backoff?: BackoffPolicy;
19
+ readonly timer?: TimerScheduler;
20
+ readonly now?: () => number;
21
+ readonly random?: () => number;
22
+ }
23
+ /** 스트리밍 소스 — IRealtimeSource 구현. 전송 원문 → 정규 페이로드 + 상태 방출. / Streaming source. */
24
+ export declare class StreamingSource<T> implements IRealtimeSource<T> {
25
+ private readonly _cfg;
26
+ private readonly _timer;
27
+ private readonly _now;
28
+ private readonly _random;
29
+ private readonly _dataListeners;
30
+ private readonly _statusListeners;
31
+ private _state;
32
+ private _lastSeq;
33
+ private _reconnect;
34
+ private _started;
35
+ private _open;
36
+ constructor(cfg: StreamingConfig<T>);
37
+ get status(): ConnectionState;
38
+ onData(listener: (p: RtPayload<T>) => void): () => void;
39
+ onStatus(listener: (s: ConnectionState) => void): () => void;
40
+ start(): void;
41
+ stop(): void;
42
+ private _connect;
43
+ private _onOpen;
44
+ private _onMessage;
45
+ private _onDrop;
46
+ private _transition;
47
+ }
@@ -0,0 +1,12 @@
1
+ import { BackoffPolicy } from './IRealtimeSource.js';
2
+ /**
3
+ * attempt(0-base) 회차의 재연결 지연(ms) 계산. base·factor^attempt, maxMs 상한, 선택적 jitter.
4
+ * / Reconnect delay(ms) for a 0-based attempt: base·factor^attempt, capped at maxMs, optional jitter.
5
+ *
6
+ * @param policy - backoff 정책 / backoff policy
7
+ * @param attempt - 0-base 재시도 회차 / 0-based retry attempt
8
+ * @param random - [0,1) 난수 주입(테스트 결정론) / injected [0,1) RNG for determinism
9
+ */
10
+ export declare function nextBackoffDelay(policy: BackoffPolicy, attempt: number, random?: () => number): number;
11
+ /** maxAttempts 도달(초과) 여부 — error 상태 표면화 판정. / Whether attempts are exhausted. */
12
+ export declare function backoffExhausted(policy: BackoffPolicy, attempt: number): boolean;
@@ -0,0 +1,13 @@
1
+ export type { RtPayload, SnapshotPayload, DeltaPayload, IRealtimeSource, ConnectionStatus, ConnectionState, RtError, BackoffPolicy, } from './IRealtimeSource.js';
2
+ export { isSeqNewer } from './IRealtimeSource.js';
3
+ export { PollingSource, type PollingConfig } from './PollingSource.js';
4
+ export { StreamingSource, type StreamingConfig, type StreamTransport } from './StreamingSource.js';
5
+ export { nextBackoffDelay, backoffExhausted } from './backoff.js';
6
+ export { BackpressureScheduler, type NormalizedBatch, type BackpressureStats, type BackpressureConfig, } from './BackpressureScheduler.js';
7
+ export { RealtimeController, type RealtimeControllerDeps } from './RealtimeController.js';
8
+ export { RtApplyCommand } from './RtApplyCommand.js';
9
+ export { LiveStateGuard, type EditConflict } from './LiveStateGuard.js';
10
+ export { FreshnessClock, type FreshnessState, type FreshnessSnapshot, type FreshnessConfig, } from './FreshnessClock.js';
11
+ export { RtAnnouncePolicy, type RtAnnouncePolicyConfig, type RtAnnounceSummary, type AppliedDelta, } from './RtAnnouncePolicy.js';
12
+ export { DefaultRtChartTargetTrigger, type RtChartTargetTrigger, type RenderTargetKind, } from './RtChartTargetTrigger.js';
13
+ export { defaultTimerScheduler, defaultFrameScheduler, type RtCommandSink, type RtCoords, type LiveStateSource, type LiveUserState, type SelectionAnchor, type ScrollAnchor, type EditingState, type TimerHandle, type TimerScheduler, type FrameScheduler, } from './ports.js';
@@ -0,0 +1,80 @@
1
+ import { ICommand } from '../command/ICommand.js';
2
+ /**
3
+ * 단일 쓰기 이음새(DD-09) 중 RT 가 쓰는 부분집합. RT 델타는 **비-undoable 백그라운드 커맨드**로
4
+ * 접어 dispatchSilent → undo 스택 미오염(userInitiated=false). beginBatch/endBatch 는 다중 델타를
5
+ * 한 프레임 브래킷으로 묶되 undo 컴포지트를 만들지 않는다(=매크로와 구별).
6
+ * / Subset of DD-09's sole write seam used by RT; silent = no undo-stack pollution.
7
+ */
8
+ export interface RtCommandSink<T = unknown> {
9
+ /** undo 스택 미적재로 커맨드 실행(do 만). / Execute a command without pushing to the undo stack. */
10
+ dispatchSilent(cmd: ICommand<T>): void;
11
+ /** 프레임 배치 시작(undo 컴포지트 아님). / Begin a (non-undoable) frame batch. */
12
+ beginBatch(): void;
13
+ /** 프레임 배치 종료. / End the frame batch. */
14
+ endBatch(): void;
15
+ }
16
+ /**
17
+ * 좌표 권위(DD-02 SSOT) 중 RT 가 쓰는 부분집합. RT 재구현 0 — rowId(안정키)↔flat index 만.
18
+ * DD-09 CoordResolver 는 indexOf/rowIdAt 을 제공하므로 얇은 이름 어댑터로 연결(통합 TODO).
19
+ * / Coordinate authority subset (DD-02 SSOT); RT never re-implements coordinate math.
20
+ */
21
+ export interface RtCoords {
22
+ /** rowId → flat index. 미존재 = -1. / rowId → flat index; absent = -1. */
23
+ rowIdToIndex(rowId: string): number;
24
+ /** flat index → rowId. 범위 밖 = undefined. / flat index → rowId; out of range = undefined. */
25
+ indexToRowId(index: number): string | undefined;
26
+ }
27
+ /** 미커밋 편집 상태(rowId 앵커). / Uncommitted edit (rowId-anchored). */
28
+ export interface EditingState {
29
+ readonly rowId: string;
30
+ readonly field: string;
31
+ readonly draftValue: unknown;
32
+ }
33
+ /** 선택 앵커(rowId 기준 — 인덱스 아님). / Selection anchor (rowId, not index). */
34
+ export interface SelectionAnchor {
35
+ readonly rowId: string;
36
+ readonly field?: string;
37
+ }
38
+ /** 스크롤 앵커(rowId + 행 내부 픽셀 오프셋). / Scroll anchor (rowId + within-row pixel offset). */
39
+ export interface ScrollAnchor {
40
+ readonly anchorRowId?: string;
41
+ readonly pixelWithinRow: number;
42
+ readonly scrollLeft: number;
43
+ }
44
+ /** 적용 전 캡처되는 사용자 상태(rowId 앵커). / User state captured before applying (rowId-anchored). */
45
+ export interface LiveUserState {
46
+ readonly selection: readonly SelectionAnchor[];
47
+ readonly scroll: ScrollAnchor;
48
+ readonly editing?: EditingState;
49
+ /** 정렬/필터 상태 서명(무효화 감지). / Sort/filter state signature. */
50
+ readonly sortFilterSig: string;
51
+ }
52
+ /**
53
+ * 선택/스크롤/편집 상태 읽기·쓰기 포트(전환 보존 계약). LiveStateGuard 가 이 위에서 캡처/복원.
54
+ * 실배선은 SelectionModel·ViewportController·CellEditManager 에 연결(통합 TODO).
55
+ * / Read/write port for selection/scroll/edit; the transition-preservation contract.
56
+ */
57
+ export interface LiveStateSource {
58
+ readSelection(): readonly SelectionAnchor[];
59
+ readScroll(): ScrollAnchor;
60
+ readEditing(): EditingState | undefined;
61
+ readSortFilterSig(): string;
62
+ writeSelection(sel: readonly SelectionAnchor[]): void;
63
+ writeScroll(scroll: ScrollAnchor): void;
64
+ writeEditing(editing: EditingState | undefined): void;
65
+ }
66
+ /** 타이머 핸들(취소 가능). / Cancelable timer handle. */
67
+ export interface TimerHandle {
68
+ cancel(): void;
69
+ }
70
+ /** 지연 실행 주입(폴링 간격·backoff). 기본 어댑터가 setTimeout 을 감싸되 테스트는 수동 시계. */
71
+ export type TimerScheduler = (cb: () => void, delayMs: number) => TimerHandle;
72
+ /** 프레임 경계 주입(백프레셔 flush). 기본 어댑터가 rAF 를 감싸되 서버/테스트는 결정론 시계. */
73
+ export type FrameScheduler = (cb: () => void) => TimerHandle;
74
+ /** 실 setTimeout 기반 기본 타이머(비테스트 기본). / Default setTimeout-based timer. */
75
+ export declare const defaultTimerScheduler: TimerScheduler;
76
+ /**
77
+ * 기본 프레임 스케줄러 — 브라우저면 rAF, 아니면 setTimeout(~16ms) 폴백(헤드리스 안전).
78
+ * / Default frame scheduler — rAF in browser, setTimeout fallback headless.
79
+ */
80
+ export declare const defaultFrameScheduler: FrameScheduler;
@@ -0,0 +1,18 @@
1
+ import { PaintAccumulator, CellRenderRequest } from './CellRenderRequest.js';
2
+ /**
3
+ * 누적 페인트를 cellEl 에 인라인으로 적용하는 humble object(테스트는 compositor/applier 만 DOM 검증).
4
+ * / Humble object that applies the accumulated paint to cellEl inline.
5
+ */
6
+ export declare class CellApplier {
7
+ /**
8
+ * 누적 → cellEl 물질화. 순서: 배경(단일+bgLayers z순) → 값 content() → 데코(z순) →
9
+ * cellStyle/classes/aria 병합. content 부재 시 raw 폴백.
10
+ * / Materialize accumulator → cellEl. Order: background → value content() → decorations →
11
+ * cellStyle/classes/aria. Raw fallback when content is absent.
12
+ *
13
+ * @param cellEl - 대상 셀 엘리먼트 / Target cell element
14
+ * @param acc - 누적 페인트 / Accumulated paint
15
+ * @param req - 원 요청(raw 폴백·힌트용) / The originating request (for raw fallback/hints)
16
+ */
17
+ apply(cellEl: HTMLElement, acc: PaintAccumulator, req: CellRenderRequest): void;
18
+ }
@@ -0,0 +1,65 @@
1
+ /** guard/circuit 이 다루는 스코프(진단 좌표). / Scope handled by guard/circuit (diagnostic coords). */
2
+ export interface StageScope {
3
+ readonly stageId: string;
4
+ readonly ri: number;
5
+ readonly ci: number;
6
+ }
7
+ /**
8
+ * 단계 회로차단기. N회 연속 실패 → open. open 이면 이후 프레임에서 호출 자체를 skip(폭주 차단).
9
+ * 성공 1회 → 실패 카운트 리셋(닫힘 복귀). onTrip 으로 관측성 이벤트 방출(REQ-T3-819).
10
+ * / Stage circuit breaker. N consecutive failures → open; while open, callers skip the stage.
11
+ * One success resets the failure count (closes). Emits onTrip for observability.
12
+ */
13
+ export declare class StageCircuitBreaker {
14
+ private _fails;
15
+ private _open;
16
+ private _tripCbs;
17
+ private readonly _threshold;
18
+ /**
19
+ * @param threshold - open 으로 넘어가는 연속 실패 임계(기본 3) / Consecutive-failure threshold (default 3)
20
+ */
21
+ constructor(threshold?: number);
22
+ /**
23
+ * 단계 실행 결과 기록. 실패 누적이 임계 도달 시 open + onTrip. 성공은 카운트 리셋.
24
+ * / Record a stage outcome. Trips open + onTrip when failures hit threshold; success resets.
25
+ *
26
+ * @param stageId - 단계 id / Stage id
27
+ * @param ok - 성공 여부 / Whether it succeeded
28
+ */
29
+ record(stageId: string, ok: boolean): void;
30
+ /** open(차단) 상태인가 — open 이면 호출측이 단계를 skip. / Whether open (callers skip the stage). */
31
+ isOpen(stageId: string): boolean;
32
+ /** 특정 단계 회로를 수동 리셋(닫힘). / Manually reset a stage's circuit (close). */
33
+ reset(stageId: string): void;
34
+ /**
35
+ * 회로 open 관측성 콜백 등록(텔레메트리·경고 UI). / Register an on-trip observability callback.
36
+ *
37
+ * @param cb - open 될 때 호출 / Called when a circuit trips open
38
+ */
39
+ onTrip(cb: (stageId: string) => void): void;
40
+ }
41
+ /**
42
+ * 셀단위 오류 경계. fn 을 try/catch 로 감싸 예외 시 fallback 을 반환(never throw to host).
43
+ * 예외는 onError 로 관측만 하고 삼킨다 — 그 셀·단계만 격리, 다른 셀/행/그리드는 무영향.
44
+ * / Cell-level error boundary. Wraps fn in try/catch, returning fallback on throw (never throws to
45
+ * host). Exceptions are observed via onError and swallowed — isolating that cell/stage only.
46
+ */
47
+ export declare class CellErrorBoundary {
48
+ private _errCbs;
49
+ /**
50
+ * fn 을 격리 실행. 예외 시 onError 방출 후 fallback 반환.
51
+ * / Run fn in isolation. On throw, emit onError then return fallback.
52
+ *
53
+ * @param scope - 진단 스코프 / Diagnostic scope
54
+ * @param fn - 실행 함수 / Function to run
55
+ * @param fallback - 실패 시 반환값 / Value returned on failure
56
+ * @returns fn 결과 또는 fallback / fn's result, or fallback
57
+ */
58
+ guard<R>(scope: StageScope, fn: () => R, fallback: R): R;
59
+ /**
60
+ * 격리된 예외 관측성 콜백 등록. / Register an observability callback for isolated exceptions.
61
+ *
62
+ * @param cb - 예외 발생 시 호출 / Called on an isolated exception
63
+ */
64
+ onError(cb: (scope: StageScope, err: unknown) => void): void;
65
+ }
@@ -0,0 +1,39 @@
1
+ import { CellRenderRequest, PaintAccumulator } from './CellRenderRequest.js';
2
+ import { CellStageRegistry } from './CellStageRegistry.js';
3
+ import { RenderBudget } from './RenderBudget.js';
4
+ import { CellApplier } from './CellApplier.js';
5
+ import { OverlayCompositor } from './OverlayCompositor.js';
6
+ import { CellErrorBoundary, StageCircuitBreaker } from './CellErrorBoundary.js';
7
+ /**
8
+ * CellPipeline — 셀 1개 합성 오케스트레이터. 협력자를 주입받아 4레인을 순회한다.
9
+ * / CellPipeline — orchestrates single-cell composition over the four lanes.
10
+ */
11
+ export declare class CellPipeline {
12
+ private readonly registry;
13
+ private readonly budget;
14
+ private readonly applier;
15
+ private readonly compositor;
16
+ private readonly boundary;
17
+ private readonly breaker;
18
+ constructor(registry: CellStageRegistry, budget: RenderBudget, applier: CellApplier, compositor: OverlayCompositor, boundary: CellErrorBoundary, breaker: StageCircuitBreaker);
19
+ /**
20
+ * 셀 렌더. never throw to host — 어떤 단계·인터셉터·물질화 실패도 그 셀만 격리한다.
21
+ * / Render a cell. Never throws to host — isolates any stage/interceptor/materialization failure.
22
+ *
23
+ * @param req - 읽기 전용 셀 요청 / Read-only cell request
24
+ * @param cellEl - 대상 셀 엘리먼트 / Target cell element
25
+ */
26
+ renderCell(req: CellRenderRequest, cellEl: HTMLElement): void;
27
+ /**
28
+ * 진단·특성화용 순수 합성(DOM 미접촉). 누적 결과(trace 포함)를 반환해 결정론 스냅샷·byte-identical
29
+ * 검증에 쓴다(§8 R4). 물질화·오버레이 합성은 하지 않는다.
30
+ * / Pure composition for diagnostics/characterization (no DOM). Returns the accumulator (with trace)
31
+ * for deterministic snapshots.
32
+ *
33
+ * @param req - 읽기 전용 셀 요청 / Read-only cell request
34
+ * @returns 누적 페인트(읽기 전용) / The accumulated paint (read-only)
35
+ */
36
+ compose(req: CellRenderRequest): PaintAccumulator;
37
+ /** 한 레인의 단계를 order 순으로 순회·격리 실행·누적. / Traverse a lane's stages, isolate, accumulate. */
38
+ private _runLane;
39
+ }