@context-action/core 1.2.6 → 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 (38) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +31 -1
  3. package/dist/element-BRlY61kW.cjs +631 -0
  4. package/dist/element-BTaXgo7n.js +597 -0
  5. package/dist/element-BTaXgo7n.js.map +1 -0
  6. package/dist/element-DPioFL7C.d.cts +163 -0
  7. package/dist/element-DPioFL7C.d.cts.map +1 -0
  8. package/dist/element-DPioFL7C.d.ts +163 -0
  9. package/dist/element-DPioFL7C.d.ts.map +1 -0
  10. package/dist/element-react.cjs +91 -0
  11. package/dist/element-react.d.cts +11 -0
  12. package/dist/element-react.d.cts.map +1 -0
  13. package/dist/element-react.d.ts +11 -0
  14. package/dist/element-react.d.ts.map +1 -0
  15. package/dist/element-react.js +85 -0
  16. package/dist/element-react.js.map +1 -0
  17. package/dist/element.cjs +9 -0
  18. package/dist/element.d.cts +3 -0
  19. package/dist/element.d.ts +3 -0
  20. package/dist/element.js +3 -0
  21. package/dist/index.cjs +154 -47
  22. package/dist/index.d.cts +2 -1
  23. package/dist/index.d.cts.map +1 -1
  24. package/dist/index.d.ts +2 -1
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +154 -47
  27. package/dist/index.js.map +1 -1
  28. package/dist/public-action-methods-C_ppItRr.d.cts +5 -0
  29. package/dist/public-action-methods-C_ppItRr.d.cts.map +1 -0
  30. package/dist/public-action-methods-C_ppItRr.d.ts +5 -0
  31. package/dist/public-action-methods-C_ppItRr.d.ts.map +1 -0
  32. package/docs/action-contracts.md +78 -0
  33. package/docs/element-host-patterns.en.md +129 -0
  34. package/docs/element-host-patterns.ko.md +116 -0
  35. package/docs/element-interop.md +138 -0
  36. package/docs/interop-review.en.md +55 -0
  37. package/docs/interop-review.ko.md +51 -0
  38. package/package.json +35 -4
@@ -0,0 +1,5 @@
1
+ //#region src/contracts/public-action-methods.d.ts
2
+ type PublicActionMethods<Actions extends object, PublicKeys extends keyof Actions = keyof Actions, ReturnMap extends Partial<Record<PublicKeys, unknown>> = Record<never, never>> = { readonly [Key in PublicKeys]: [Actions[Key]] extends [void | undefined] ? () => Key extends keyof ReturnMap ? Promise<ReturnMap[Key]> : Promise<void> : (payload: Actions[Key]) => Key extends keyof ReturnMap ? Promise<ReturnMap[Key]> : Promise<void>; };
3
+ //#endregion
4
+ export { PublicActionMethods as t };
5
+ //# sourceMappingURL=public-action-methods-C_ppItRr.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"public-action-methods-C_ppItRr.d.cts","names":[],"sources":["../src/contracts/public-action-methods.ts"],"mappings":";KACY,oBACV,wBACA,yBAAyB,gBAAgB,SACzC,kBAAkB,QAAQ,OAAO,wBAAwB,oCAG/C,OAAO,cAAc,QAAQ,yCAC7B,kBAAkB,YAAY,QAAQ,UAAU,QAAQ,iBAC7D,SAAS,QAAQ,SAAS,kBAAkB,YAAY,QAAQ,UAAU,QAAQ"}
@@ -0,0 +1,5 @@
1
+ //#region src/contracts/public-action-methods.d.ts
2
+ type PublicActionMethods<Actions extends object, PublicKeys extends keyof Actions = keyof Actions, ReturnMap extends Partial<Record<PublicKeys, unknown>> = Record<never, never>> = { readonly [Key in PublicKeys]: [Actions[Key]] extends [void | undefined] ? () => Key extends keyof ReturnMap ? Promise<ReturnMap[Key]> : Promise<void> : (payload: Actions[Key]) => Key extends keyof ReturnMap ? Promise<ReturnMap[Key]> : Promise<void>; };
3
+ //#endregion
4
+ export { PublicActionMethods as t };
5
+ //# sourceMappingURL=public-action-methods-C_ppItRr.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"public-action-methods-C_ppItRr.d.ts","names":[],"sources":["../src/contracts/public-action-methods.ts"],"mappings":";KACY,oBACV,wBACA,yBAAyB,gBAAgB,SACzC,kBAAkB,QAAQ,OAAO,wBAAwB,oCAG/C,OAAO,cAAc,QAAQ,yCAC7B,kBAAkB,YAAY,QAAQ,UAAU,QAAQ,iBAC7D,SAAS,QAAQ,SAAS,kBAAkB,YAAY,QAAQ,UAAU,QAAQ"}
@@ -0,0 +1,78 @@
1
+ # Core action contracts
2
+
3
+ The default `@context-action/core` entry is the action control plane. It does not
4
+ own Store state, React subscriptions, DOM, or time-travel history. The package also
5
+ contains opt-in [Element transport and React host entries](element-interop.md),
6
+ which are not reachable from the default runtime or declaration graph.
7
+
8
+ ## Responsibilities by category
9
+
10
+ | Category | Contract | Owner |
11
+ |---|---|---|
12
+ | Registration | action key, handler role, priority, lifecycle | `ActionRegister` |
13
+ | Admission | guard, abort, payload validation, timeout | `ActionGuard` / pipeline controller |
14
+ | Execution | sequential, parallel, race, scheduling | execution modes |
15
+ | Results | typed result collection and error policy | result handlers / `dispatchWithResult` |
16
+ | Observation | success/failure/always observers | observer handlers |
17
+ | Lifecycle | closing, destroyed, active dispatch cleanup | `ActionRegister` |
18
+ | State commit | snapshot, store mutation, undo/redo | `@context-action/react` store layer |
19
+
20
+ Handlers should express intent and domain work. A handler may call a Store
21
+ writer, but the action runtime does not infer which state changes belong to one
22
+ user action. Atomic multi-store undo therefore requires an explicit transaction
23
+ coordinator at the application/store layer.
24
+
25
+ ## Stable boundary
26
+
27
+ The public action contract is:
28
+
29
+ ```ts
30
+ interface ActionBoundary<Actions> {
31
+ dispatch<K extends keyof Actions>(action: K, payload: Actions[K]): Promise<unknown>;
32
+ register<K extends keyof Actions>(action: K, handler: unknown, config?: unknown): () => void;
33
+ destroy(): Promise<void> | void;
34
+ }
35
+ ```
36
+
37
+ The concrete `ActionRegister` exposes additional controls for guards, results,
38
+ observers, and scheduling. Adapters should depend on the smallest role they
39
+ need. State metadata such as `transactionId`, `origin`, and `label` should be
40
+ introduced at the commit boundary and passed through explicitly rather than
41
+ being inferred from handler names.
42
+
43
+ ### Queue re-entry
44
+
45
+ `registry: { useConcurrencyQueue: true }` uses a single execution slot. A
46
+ handler that awaits another dispatch on the same register must bypass that
47
+ slot explicitly:
48
+
49
+ ```ts
50
+ register.register('outer', async () => {
51
+ await register.dispatch('inner', undefined, { immediate: true });
52
+ });
53
+ ```
54
+
55
+ Without `immediate: true`, the nested dispatch waits behind the outer handler
56
+ while the outer handler waits for the nested promise, so the two operations
57
+ cannot settle. `queuePriority` only orders work that is already waiting; it
58
+ does not make an awaited nested dispatch re-entrant. Use an explicit immediate
59
+ dispatch for nested orchestration, or dispatch the follow-up after the outer
60
+ action has settled.
61
+
62
+ ## Maintenance rule
63
+
64
+ Changes to execution order, once-handler claiming, abort semantics, result
65
+ selection, or destroy behavior are action contract changes. They require a
66
+ focused contract test and a downstream Store integration test when a handler
67
+ commits state. Changes to Store history or snapshot identity belong to the
68
+ React store contracts and must not be hidden as ActionRegister refactors.
69
+
70
+ ## Dispatch trace bridge
71
+
72
+ `subscribeDispatchTrace()` emits exactly one `started` and one `settled` event
73
+ per public dispatch. The event carries a stable `dispatchId`, action name,
74
+ terminal status, timing, and optional trace metadata from `DispatchOptions.trace`.
75
+ Core does not create or mutate Store transactions. The React adapter can bind
76
+ these events to explicit Store participants with `bindActionTransactions()`.
77
+ This keeps the dependency direction `core → trace contract ← store adapter` and
78
+ prevents Core from importing React or Store classes.
@@ -0,0 +1,129 @@
1
+ # Typed Vue, Svelte and Angular host patterns
2
+
3
+ [한국어](element-host-patterns.ko.md) · [Shared lifecycle contract](element-interop.md)
4
+
5
+ Status: copyable reference implementations under `packages/core/examples/element-hosts/`.
6
+ They are not public package exports and are not included in the published tarball.
7
+ No framework runtime, peer or compiler is added to Core's package dependencies.
8
+ The existing Core/UI release-floor restriction still applies.
9
+
10
+ ## Shared boundary
11
+
12
+ The counter reference shares `CounterProps`, `CounterInput`, a semantic
13
+ `CounterHandle`, event names and the property map. It does not expose raw DOM or
14
+ renderer state through its handle. A request does not commit input; the host must
15
+ confirm a new snapshot. Invalid counter input preserves the previous valid value.
16
+
17
+ Copy the adapter for your framework and `shared/connect-binding.ts` into your
18
+ application. Replace the counter contract and tag with your component's public
19
+ contract. Import Core only through `/element`, not a package `src`/`dist` path.
20
+ Copying the examples is not a substitute for approving the future Core version
21
+ that contains that export.
22
+
23
+ `connectBinding` releases listeners if the first update throws. It does not roll
24
+ back earlier setter side effects. Vue/Angular register their cleanup reference
25
+ before that update, so synchronous setter events can tear down the host safely.
26
+ These reference adapters default to fail-fast
27
+ assignment; the existing Lit wrapper's best-effort policy is unchanged.
28
+ Provide complete snapshots and replace their identity when changing inputs.
29
+ There is no implicit deep watch, state-container subscription, or business handler.
30
+
31
+ ## Vue
32
+
33
+ `vue/element-directive.ts` exports `createElementDirective<Props>()`, typed as a
34
+ Vue `ObjectDirective<HTMLElement, Props>`. It captures config/policy once, uses
35
+ one binding per node in a WeakMap, updates on `updated`, and disposes on
36
+ `beforeUnmount`. The factory itself imports Vue types only.
37
+
38
+ `vue/Host.vue` shows local `<script setup>` registration using `vElement` and
39
+ `v-element="snapshot"`. Configure `isCustomElement` in the SFC build compiler
40
+ (not only runtime app config) for the host tag. The gate does so when compiling
41
+ the template and verifies the actual SFC with `vue-tsc`.
42
+
43
+ ## Svelte
44
+
45
+ `svelte/element-action.ts` exports `createElementAction<Props>()`, checked against
46
+ Svelte's actual `Action<HTMLElement, Props>` type. A complete snapshot is required;
47
+ undefined action input throws. Action update/destroy delegate to the binding.
48
+
49
+ `svelte/Host.svelte` uses the action with a typed readable snapshot source. The
50
+ source is host-owned; this does not standardize Store read protocols. The same
51
+ component is checked with `svelte-check` and compiled for client/server execution.
52
+
53
+ ## Angular
54
+
55
+ `angular/element-binding.directive.ts` is an actual standalone decorated directive,
56
+ not a runtime decorator factory. `angular/host.component.ts` imports it in a typed
57
+ template with `CUSTOM_ELEMENTS_SCHEMA` for the native tag.
58
+
59
+ - Required `caElementBinding` supplies config; it is fixed after mount. A new
60
+ config reference after mount throws: remount the host instead of silently
61
+ abandoning previously owned properties.
62
+ - Required `caElementInput` supplies complete snapshots; new Input references are
63
+ applied in `ngOnChanges`. Binding starts in `ngAfterViewInit`.
64
+ - `DestroyRef` owns cleanup, not the component renderer.
65
+ - `isPlatformBrowser(PLATFORM_ID)` prevents server-side native DOM binding.
66
+
67
+ The gate runs Angular's full compiler with `strictTemplates` and
68
+ `strictInjectionParameters`. Its Angular 20 compiler requires TypeScript <6, so
69
+ the **isolated consumer** uses TypeScript 5.9.3; workspace TypeScript is unchanged.
70
+
71
+ ## Evidence and limits
72
+
73
+ Run `pnpm verify:element-hosts` after editing these patterns. It uses Core's local
74
+ packed public entry and pinned Vue 3.5.44 / Svelte 5.57.2 / Angular 20.3.34,
75
+ vue-tsc 3.3.13 and svelte-check 4.7.7. It checks:
76
+
77
+ - valid typed templates plus deliberately invalid numeric payloads rejected by
78
+ **each** template compiler; negative Handle/property-map type contracts;
79
+ - native default preservation, object identity, request/commit separation,
80
+ handler replacement/omission, teardown, detached handles and remount;
81
+ - per-node isolation, config capture and cleanup after failed initialization;
82
+ - Angular's fixed-config rule, server DOM guard and DestroyRef cleanup;
83
+ - inert server shells rendered in fresh Node processes without injected browser
84
+ globals (Angular uses an exact allowed host, not a wildcard).
85
+
86
+ Client lifecycle evidence uses JSDOM and a native probe. Server evidence covers
87
+ the host shell only: it does not render the internals of a Preact/Lit component,
88
+ serialize interactive property state or certify hydration. Real-browser FACE,
89
+ arbitrary framework versions, multiple-renderer cross-products and released
90
+ production adapter packages remain out of scope. The focused compiler gate is
91
+ explicit; ordinary Core type-checking does not install these host dependencies.
92
+
93
+ ## Real browser gate
94
+
95
+ `pnpm verify:element-host-browser` runs the typed/JSDOM/server gate first, then
96
+ bundles the **same compiled reference templates** into a temporary loopback page.
97
+ It requires a connected `ego-browser` runtime. No additional workspace framework
98
+ dependency or public package export is introduced. Angular uses real
99
+ `createApplication` / `createComponent` / attach/destroy lifecycles rather than
100
+ TestBed. This verification bundle includes the compiler/dev runtimes; it is not
101
+ a production-linked deployment artifact.
102
+
103
+ The driver performs one trusted native Shadow DOM button click for each host
104
+ before running its 17 checks: untouched defaults, property identity, semantic
105
+ handle, trusted request, request/commit separation, rejected input, imperative
106
+ event, stable listeners, no input echo, handler replacement, object receiver,
107
+ omission, ownership release, unmount, detached handle, remount and final cleanup.
108
+ No unhandled browser errors are allowed. All hosts are unmounted at completion.
109
+
110
+ Only `/` and the bundled `/app.js` are served on a random `127.0.0.1` port; this
111
+ does not expose the workspace as a file server. The driver closes its own browser
112
+ space after success, and the gate closes its server even on failure. On browser
113
+ failure the task space remains available for diagnosis; it must not be replaced
114
+ with a new space just to bypass a blocked or user-controlled page.
115
+
116
+ Evidence includes the browser user-agent, explicit framework pins, per-host check
117
+ names, driver transcript, and served-bundle SHA-256 in a temporary directory
118
+ printed by the gate. `CONTEXT_ACTION_BROWSER_EVIDENCE_DIR` selects a new destination.
119
+ The destination must be empty; nonempty directories are rejected to avoid mixing
120
+ old and new receipts. A recovered
121
+ driver transcript is evidence of that browser run, not a new run or a release
122
+ receipt; do not fabricate a lost artifact hash.
123
+
124
+ `pnpm test:element-host-browser` checks result parsing without browser access.
125
+ Both stdout and stderr are accepted, but missing/duplicate/partial results,
126
+ changed version pins, untrusted clicks and browser errors fail closed.
127
+
128
+ This adds **current ego Chromium + native Shadow DOM probe** evidence only. It
129
+ does not certify Firefox/WebKit, FACE, renderer cross-products or hydration.
@@ -0,0 +1,116 @@
1
+ # Vue·Svelte·Angular 타입 기반 호스트 패턴
2
+
3
+ [English](element-host-patterns.en.md) · [공통 수명 계약](element-interop.md)
4
+
5
+ 상태: `packages/core/examples/element-hosts/`의 복사 가능한 참조 구현입니다.
6
+ 공개 package export가 아니며 배포 tarball에도 포함하지 않습니다. Core에 프레임워크
7
+ 런타임·peer·컴파일러 의존성을 추가하지 않았습니다. 기존 Core/UI 배포 버전 승인 조건도 유지합니다.
8
+
9
+ ## 공통 경계
10
+
11
+ counter 참조 구현은 `CounterProps`, `CounterInput`, 의미 중심 `CounterHandle`,
12
+ 이벤트 이름과 property map을 공유합니다. Handle에는 DOM·렌더러 상태를 노출하지 않습니다.
13
+ 요청 이벤트는 입력 확정이 아니며 호스트가 새 snapshot을 넣어야 확정됩니다.
14
+ 잘못된 counter 입력은 이전 유효 값을 보존합니다.
15
+
16
+ 선택한 어댑터와 `shared/connect-binding.ts`를 애플리케이션으로 함께 복사하고,
17
+ counter 계약·태그를 실제 컴포넌트의 공개 계약으로 교체합니다. Core는 `/element`
18
+ 공개 경로로만 가져옵니다. 예제 복사가 새 export를 포함한 Core 배포 버전 승인을
19
+ 대체하지는 않습니다.
20
+
21
+ `connectBinding`은 최초 update 실패 시 먼저 연결한 listener를 해제합니다.
22
+ 이미 실행된 setter 부작용을 rollback하지는 않습니다. Vue/Angular는 update 전에
23
+ cleanup 참조를 등록하여 동기 setter 이벤트 중 호스트가 해제되어도 정리합니다.
24
+ 참조 어댑터는 기본적으로
25
+ 대입 오류를 throw하며, 기존 Lit wrapper의 best-effort 정책은 바꾸지 않습니다.
26
+ 입력은 전체 snapshot이고 변경 시 새 객체를 제공합니다. 자동 deep watch·Store
27
+ 구독·업무 handler는 추가하지 않습니다.
28
+
29
+ ## Vue
30
+
31
+ `vue/element-directive.ts`의 `createElementDirective<Props>()`는 실제 Vue의
32
+ `ObjectDirective<HTMLElement, Props>` 타입을 사용합니다. config·오류 정책은
33
+ 생성 시 캡처하고 WeakMap으로 DOM node마다 binding을 분리합니다. `updated`에서
34
+ 동기화하고 `beforeUnmount`에서 해제합니다. factory의 Vue import는 타입 전용입니다.
35
+
36
+ `vue/Host.vue`는 `<script setup>`의 `vElement`와 `v-element="snapshot"` 사용법을
37
+ 보입니다. 태그의 `isCustomElement`는 runtime app 설정뿐 아니라 **SFC 빌드 컴파일러**에
38
+ 설정해야 합니다. 게이트는 실제 SFC를 `vue-tsc`로 검사한 후 이 설정으로 컴파일합니다.
39
+
40
+ ## Svelte
41
+
42
+ `svelte/element-action.ts`의 `createElementAction<Props>()`는 실제 Svelte의
43
+ `Action<HTMLElement, Props>` 타입으로 검사합니다. 전체 snapshot이 필수이며
44
+ undefined 인자는 throw합니다. action의 update/destroy는 binding에 위임합니다.
45
+
46
+ `svelte/Host.svelte`는 타입이 지정된 readable source와 action을 연결합니다.
47
+ source는 호스트 소유이며 Store 읽기 계약의 통합을 의미하지 않습니다. 같은 컴포넌트를
48
+ `svelte-check`로 검사하고 client/server 용으로 컴파일합니다.
49
+
50
+ ## Angular
51
+
52
+ `angular/element-binding.directive.ts`는 실제 decorator를 사용하는 standalone
53
+ directive이며 runtime decorator factory가 아닙니다. `angular/host.component.ts`는
54
+ 타입이 검사되는 템플릿에서 directive와 native tag용 `CUSTOM_ELEMENTS_SCHEMA`를 사용합니다.
55
+
56
+ - 필수 `caElementBinding`은 mount 후 고정입니다. 새 config 참조를 넣으면 throw하며,
57
+ 기존 property 소유권을 조용히 버리는 대신 호스트를 다시 mount해야 합니다.
58
+ - 필수 `caElementInput`은 전체 snapshot입니다. 새 Input 참조는 `ngOnChanges`에서
59
+ 적용하고 최초 binding은 `ngAfterViewInit`에서 시작합니다.
60
+ - cleanup은 `DestroyRef`가 소유하며 renderer를 dispose하지 않습니다.
61
+ - `isPlatformBrowser(PLATFORM_ID)`로 서버에서 native DOM binding을 생략합니다.
62
+
63
+ 게이트는 `strictTemplates`·`strictInjectionParameters`를 켠 Angular full compiler를
64
+ 실행합니다. Angular 20 컴파일러는 TypeScript <6을 요구하므로 **격리 consumer만**
65
+ TypeScript 5.9.3을 사용합니다. workspace TypeScript는 변경하지 않습니다.
66
+
67
+ ## 근거와 제한
68
+
69
+ 패턴을 바꾼 뒤 `pnpm verify:element-hosts`를 실행합니다. 로컬 Core tarball의 공개
70
+ 경로와 Vue 3.5.44 / Svelte 5.57.2 / Angular 20.3.34, vue-tsc 3.3.13,
71
+ svelte-check 4.7.7 고정 버전으로 다음을 확인합니다.
72
+
73
+ - 유효한 typed template과 각 템플릿 컴파일러의 잘못된 숫자 payload 거부,
74
+ Handle·property map의 음성 타입 검사
75
+ - native 기본값·객체 identity·요청/확정 분리·handler 교체/제거·해제·detach·재마운트
76
+ - node별 격리·config 캡처·최초 입력 실패 후 listener cleanup
77
+ - Angular의 고정 config·server DOM 접근 방지·DestroyRef cleanup
78
+ - 브라우저 전역을 주입하지 않은 별도 Node 프로세스의 비활성 서버 호스트 마크업
79
+ (Angular allowed host는 wildcard가 아닌 정확한 호스트 사용)
80
+
81
+ client lifecycle은 JSDOM/native probe 근거입니다. 서버 근거는 호스트 shell만
82
+ 대상으로 하며 Preact/Lit 내부 렌더링·인터랙티브 property 상태 직렬화·hydration을
83
+ 보장하지 않습니다. 실제 브라우저 FACE·모든 프레임워크 버전·렌더러 조합·공개
84
+ production 어댑터 패키지는 범위 밖입니다. 이 컴파일러 게이트는 별도 명령이며
85
+ 기본 Core 타입 검사가 호스트 의존성을 자동 설치하지 않습니다.
86
+
87
+ ## 실제 브라우저 게이트
88
+
89
+ `pnpm verify:element-host-browser`는 typed/JSDOM/server 검증 뒤 **같은 컴파일된
90
+ 참조 템플릿**을 임시 loopback 페이지로 번들링합니다. 연결된 `ego-browser` 런타임이
91
+ 필요하며 workspace 프레임워크 의존성·공개 export는 추가하지 않습니다. Angular는
92
+ TestBed가 아닌 실제 `createApplication` / `createComponent` / attach/destroy 수명을
93
+ 사용합니다. 검증 번들에는 compiler/dev 런타임이 들어가므로 production 배포 산출물은 아닙니다.
94
+
95
+ driver는 각 호스트에서 실제 trusted Shadow DOM 버튼 클릭을 한 번씩 실행한 뒤
96
+ 17개 항목을 검사합니다. 기본값·property identity·의미 중심 Handle·trusted 요청·
97
+ 요청/확정 분리·입력 거부·명령 이벤트·listener 안정성·no echo·handler 교체·object
98
+ receiver·제거·소유권 반환·unmount·detach·remount·최종 cleanup입니다. 미처리 브라우저
99
+ 오류는 허용하지 않으며 종료 시 모든 호스트를 unmount합니다.
100
+
101
+ 무작위 `127.0.0.1` 포트에서 `/`와 번들 `/app.js`만 제공합니다. workspace 전체를
102
+ file server로 열지 않습니다. 성공 시 driver가 자기 브라우저 공간을 닫고, 게이트는
103
+ 실패 시에도 자기 서버를 종료합니다. 브라우저 실패 시에는 진단용 공간을 유지하며,
104
+ 막혔거나 사용자 제어 중인 페이지를 우회하려고 새 공간을 만들지 않습니다.
105
+
106
+ 출력되는 임시 디렉터리에 browser user-agent·고정 프레임워크 버전·항목별 결과·driver
107
+ 로그·제공한 번들의 SHA-256을 기록합니다. `CONTEXT_ACTION_BROWSER_EVIDENCE_DIR`로 새
108
+ 저장 경로를 지정할 수 있습니다. 이전 영수증과 섞이지 않도록 비어 있지 않은
109
+ 디렉터리는 거부합니다. 복구한 driver 로그는 해당 실행의 근거이지 새로운 실행·릴리스 영수증이
110
+ 아니며, 잃어버린 산출물 hash를 만들어 넣지 않습니다.
111
+
112
+ `pnpm test:element-host-browser`는 브라우저 없이 수집 코드를 검사합니다. stdout와
113
+ stderr를 모두 받되 결과 누락·중복·부분 통과·버전 변경·untrusted 클릭·브라우저 오류는 거부합니다.
114
+
115
+ 이번 근거는 **현재 ego Chromium + native Shadow DOM probe**에 한정합니다.
116
+ Firefox/WebKit·FACE·렌더러 조합·hydration 검증 완료를 의미하지 않습니다.
@@ -0,0 +1,138 @@
1
+ # Element transport and host lifecycle adapters
2
+
3
+ Local candidate, not yet published. `@context-action/core@1.2.6` in the registry
4
+ does not contain these proposed entries. Core/UI publication needs an approved
5
+ cohort and a minimum Core version containing the exports. Workspace ranges are
6
+ local wiring, not an approved release dependency floor.
7
+
8
+ ## Entries and ownership
9
+
10
+ | Entry | Owns | Does not reach |
11
+ | --- | --- | --- |
12
+ | `@context-action/core` | Existing Action runtime, pure `PublicActionMethods` type | Element/DOM types, React runtime/types |
13
+ | `@context-action/core/element` | `createElementBinding`, `createElementFacade`, `toReactPartProps`, `createSyncActionPipeline`, `createRovingFocusController`, `createPointerGestureSession`, DOM transport contracts | React, Vue, Svelte, Angular, Lit, Preact |
14
+ | `@context-action/core/element/react` | Injected-runtime `createReactElementBridge` and React component types | Store/Mutative or a statically imported React runtime |
15
+
16
+ Core declares no framework runtime dependency or peer constraint: the React
17
+ factory receives the caller's runtime rather than resolving it. Direct consumers
18
+ of `/element/react` provide their own React runtime and React TypeScript declarations
19
+ (React 18/19 are tested). Existing UI adapters retain their React peer declarations.
20
+ This avoids imposing package-wide React version constraints on Action-only hosts.
21
+ Vue/Svelte/Angular remain host-owned dependencies. The internal ordinary-object facade uses Reflect/descriptors/WeakMap;
22
+ only the public Element specialization constrains its target to HTMLElement.
23
+
24
+ Preact/Lit compatibility wrappers preserve their names, overloads and aliases.
25
+ Preact still throws input assignment errors; Lit still ignores them. Both keep
26
+ best-effort omission cleanup. Native rendering, FACE, context DI, SSR/hydration,
27
+ component validation, Store read protocols and request/commit policies remain
28
+ outside this machinery. No automatic `.value` snapshot unwrapping is performed.
29
+
30
+ ## Native binding lifecycle
31
+
32
+ ```ts
33
+ import { createElementBinding } from '@context-action/core/element';
34
+
35
+ interface Input {
36
+ items?: readonly string[] | undefined;
37
+ onRequest?: ((event: CustomEvent<string>) => void) | undefined;
38
+ }
39
+ const binding = createElementBinding<Input>(element, {
40
+ attributes: { role: 'role', disabled: 'aria-disabled' },
41
+ styles: { hitSize: '--handle-hit-size', left: 'left' },
42
+ properties: ['items'],
43
+ events: { onRequest: 'item-request' },
44
+ }, { assignmentErrors: 'throw' });
45
+ binding.update({ items, onRequest });
46
+ binding.update({ onRequest }); // releases previously assigned items/attributes/styles once
47
+ binding.dispose();
48
+ ```
49
+
50
+ - Config is captured at construction. Inputs are **complete snapshots**, not patches.
51
+ - `update` reconciles in deterministic order: **events → attributes → styles → properties**, so synchronous setter events see the current handler, attribute, and style state. Attach after native creation; constructor and initial `connectedCallback` events are not captured retroactively.
52
+ - `updateEvents`, `updateAttributes`, `updateStyles`, and `updateProperties` let a host choose its own lifecycle timing.
53
+ - `attributes` and `styles` bindings track an ownership ledger per binding instance: omitted keys are removed (`removeAttribute` / `removeProperty`) only for keys previously written by that binding, leaving host-owned attributes, CSS custom properties (`--*`), and inline styles untouched. Boolean attributes (`true` writes `""`; `false`, `null`, and `undefined` remove the attribute) and style strings (`""`, `null`, or `undefined` removes the property) normalize consistently.
54
+ - Omission clears only previously attempted writes, once. Untouched defaults survive.
55
+ Explicit undefined remains an assignment (for properties) or removal (for attributes/styles). Objects keep identity; no serialization,
56
+ validation, diff/equality filtering, rollback or clone is added.
57
+
58
+ ## Headless UI interaction and framework projection primitives
59
+
60
+ `@context-action/core/element` also exports framework-neutral headless primitives for Vanilla DOM, custom elements, and React/framework consumers without adding a UI framework dependency:
61
+
62
+ - `createSyncActionPipeline`: Three-phase synchronous pipeline (`registerGuard` with `abort`/`modifyPayload`, `register` with `setResult`, and `registerObserver` with `when: 'success' | 'failure' | 'always'`, `priority`, and `once`) tailored for synchronous pointer/keyboard interactions where DOM events cannot await microtasks.
63
+ - `createRovingFocusController`: ARIA composite navigation helper supporting `'horizontal'`, `'vertical'`, and `'both'` orientations, `Arrow*` / `Home` / `End` keys, disabled item skipping, looping, and roving `getTabIndex(id)` (`0` vs `-1`).
64
+ - `createPointerGestureSession`: Pointer gesture lifecycle manager handling primary-button gating, `onStart` guard rejection, automatic `setPointerCapture`/`releasePointerCapture`, `deltaX`/`deltaY` & modifier tracking (`shiftKey`, `altKey`, `ctrlKey`, `metaKey`), and `Escape` cancellation.
65
+ - `toReactPartProps(partProps, config)`: Projects any headless part snapshot plus its `ElementBindingConfig` into a React-compatible props bag (mapping `attributes`, CSS custom/inline `styles` into `style`, and event names into `on<Event>` handlers).
66
+ - **Statechart & Effect Bridges**: Dedicated integration adapters for XState v5/v6 (`@context-action/xstate`) and Effect v4 / `@xstate/effect` (`@context-action/xstate/effect`) live in the separate `@context-action/xstate` package ([architecture specification](../../xstate/docs/xstate-effect-integration.md)), keeping `@context-action/core` strictly zero-dependency.
67
+ - Stable function/object handlers reuse listeners. Changed/invalid/omitted handlers
68
+ remove prior listeners; object receivers remain intact. Multiple prop names may
69
+ map to one event and remain independent subscriptions.
70
+ - Setter throws follow the selected policy; earlier side effects are not rolled back.
71
+ A swallowed failure never confirms a commit.
72
+ - `disconnectEvents()` is replayable, retaining property ownership. `dispose()` is
73
+ terminal/idempotent; later updates throw. Neither resets properties, calls the
74
+ renderer's dispose, nor removes its DOM. Caller drops its controller reference
75
+ after disposal. Target replacement requires a new binding and old disposal.
76
+ - Disposal during a synchronous event stops later property writes. Nested updates
77
+ throw rather than silently interleave snapshots; schedule the next host update.
78
+
79
+ The React adapter reconciles events before properties in its layout effect (or its
80
+ effect fallback during SSR), so synchronous setter events caused by a bridge
81
+ snapshot reach the current-render handler. A passive effect replay reconnects
82
+ listeners after StrictMode cleanup without changing property ownership. Constructor
83
+ and initial `connectedCallback` events can still precede bridge creation and are not
84
+ replayed. When the callback ref detaches or a host is replaced, the bridge disposes
85
+ the old binding; the default forwarded ref follows the current host. Unmount clears
86
+ the ref and listeners. No renderer teardown is owned by the bridge.
87
+
88
+ Facades are frozen allow-list projections, not deep-frozen state or revocable
89
+ capabilities. Detached lazy access throws, but a previously captured bound method
90
+ can still call/retain the previous target. Method completion does not imply DOM
91
+ paint; a request event does not imply a state commit.
92
+
93
+ ## Vue, Svelte and Angular host boundaries
94
+
95
+ No universal hook API or released production adapter package is introduced.
96
+ Copyable TypeScript reference modules live under `examples/element-hosts/` and
97
+ delegate to the same DOM binding. See [typed host patterns (EN)](element-host-patterns.en.md)
98
+ or [한국어](element-host-patterns.ko.md) for usage and evidence.
99
+
100
+ | Host | Lifecycle mapping | Reference source (under `examples/element-hosts/`) |
101
+ | --- | --- | --- |
102
+ | Vue | directive mounted → binding; updated → update; beforeUnmount → dispose | `vue/element-directive.ts`, `vue/Host.vue` |
103
+ | Svelte | element action → binding; action update → update; action destroy → dispose | `svelte/element-action.ts`, `svelte/Host.svelte` |
104
+ | Angular | ngAfterViewInit → binding; ngOnChanges via Input → update; DestroyRef → dispose; skip server binding | `angular/element-binding.directive.ts`, `angular/host.component.ts` |
105
+
106
+ `pnpm verify:element-hosts` installs pinned frameworks outside the workspace and
107
+ type-checks the actual templates (including required failures for invalid payloads),
108
+ then tests native defaults, object identity, handler replacement/removal, omission,
109
+ teardown/remount and failed-initialization cleanup. Client evidence is **JSDOM**.
110
+ Fresh server processes render inert host shells without injected browser globals;
111
+ this is not component-internal SSR, hydration, arbitrary version support, browser
112
+ FACE or renderer cross-product certification. Framework-native
113
+ custom-element recognition (`isCustomElement`, Angular schemas, etc.) stays with
114
+ the application. Upgrade fixture pins deliberately and rerun the contract.
115
+
116
+ ## Verification
117
+
118
+ ```sh
119
+ pnpm --filter @context-action/core type-check
120
+ pnpm verify:element-unit
121
+ pnpm verify:element-interop
122
+ pnpm verify:element-hosts
123
+ pnpm verify:element-host-browser # optional: connected ego-browser runtime
124
+ ```
125
+
126
+ The installed interop gate checks no-framework import and strict Node-only root
127
+ declarations (ES2022 + Node types, no DOM lib), then separate strict ESM/CJS programs
128
+ and both UI wrappers on React 18/19. Root Node types still describe existing
129
+ AbortSignal/timer APIs; this work does not replace them with DOM declarations.
130
+ Existing renderer suites and actual Preact/Lit replacement evidence remain required.
131
+ The mixed Lit ESM/CJS global declaration conflict remains documented in the
132
+ [English requirements review](interop-review.en.md) / [한국어 검토](interop-review.ko.md).
133
+
134
+ The opt-in browser gate reuses those compiled reference templates with real
135
+ framework applications and a native Shadow DOM probe. It performs trusted clicks
136
+ and 17 lifecycle checks per framework through ego-browser, recording browser and
137
+ bundle evidence. See the typed host guide for prerequisites and receipt scope;
138
+ this is not hydration, FACE or a renderer cross-product guarantee.
@@ -0,0 +1,55 @@
1
+ # Shared element interface requirements review
2
+
3
+ [한국어](interop-review.ko.md) · [Ownership and limitations](element-interop.md)
4
+
5
+ Status: Core subpath implementation adopted for local work; public version/cohort and dependency floors remain unapproved.
6
+
7
+ | Requirement | Shared responsibility / evidence |
8
+ | --- | --- |
9
+ | Renderer-independent consumer contract | `ElementBridgeContract`, semantic `CounterHandle` fixture; no Lit/Preact/Signal types in the host contract |
10
+ | Existing entry points and call forms | Preact root and `/react-bridge` facade exports; Lit object/two-argument forms and aliases remain |
11
+ | Same Action/Ref orchestration | `example/src/pages/integrations/element-interop.contract.test.tsx` mounts each real renderer and replaces Preact with Lit using one host |
12
+ | Input validation and previous valid state | Invalid facade input throws without replacing confirmed input; fixture setters own validation |
13
+ | Request is not commit | `requestIncrement()` only emits a frozen `count-request`; host-confirmed input changes the state |
14
+ | No input echo | Initial input, confirmed input and reset do not re-emit the request |
15
+ | No DOM/signal leakage | Explicit facade allow-list; host ref exposes only `input`, `getSnapshot`, `requestIncrement`; detached facade access fails |
16
+ | Defaults and omission | Untouched defaults survive; only bridge-owned input is cleared; explicit undefined remains an assignment |
17
+ | Deterministic event lifetime | Shared unit suite and both renderer bridge suites cover identity reconciliation, StrictMode, handler replacement and unmount |
18
+ | Shared installed declarations | `pnpm verify:element-interop` compiles ESM/CJS public contracts with negative type assertions |
19
+ | One host React runtime | Adapters pass their React runtime into shared implementation; local packages need not use the same development React version |
20
+ | Non-React host lifecycles | `pnpm verify:element-hosts`: reusable typed Vue 3.5.44 directive, Svelte 5.57.2 action, Angular 20.3.34 standalone directive; actual positive/negative template checks, JSDOM lifecycles and inert server shells, not released adapters or hydration/browser certification |
21
+ | Native browser lifecycle | `pnpm verify:element-host-browser`: same compiled sources in real framework apps, trusted Shadow DOM clicks and 17 checks per host; current ego Chromium only, not hydration/FACE/renderer cross-products |
22
+ | DOM/React separation | Node-only root declarations and no-framework import; generic binding tests cover event-before-setter order, reentrant disposal and terminal/replayable cleanup |
23
+ | No framework runtime coupling | Shared root imports without React/Preact/Lit or HTMLElement globals; UI packages do not depend on each other's renderer |
24
+ | Release safety | No existing versions changed; public Core/UI candidates require an approved cohort and Core dependency floor containing the new exports |
25
+
26
+ This is a **transport/host interface** consolidation, not a universal Web Component
27
+ base class. CSS parts, slots, accessibility, form semantics, connection-resource
28
+ ownership, SSR/hydration and business validation remain per-component contracts.
29
+ Preserving method signatures does not prove equivalent business meaning. Consumers
30
+ must adopt a shared semantic contract deliberately, as the controlled-counter
31
+ fixture does; arbitrary existing components are not automatically substitutable.
32
+
33
+ Intentional compatibility policy: Preact retains fail-fast property assignment,
34
+ while Lit retains best-effort assignment. Both use best-effort omission cleanup.
35
+ The common implementation makes this adapter policy explicit instead of silently
36
+ merging distinct failure behavior. Preact now preserves untouched defaults and
37
+ stable listeners. Tests prove candidate behavior, not semver approval.
38
+
39
+ Browser review also found that the existing Preact showcase declared properties
40
+ without implementing their accessors. Its stepper/badge now implement typed
41
+ `value/min/max/count` accessors with validation and no programmatic-input echo;
42
+ the showcase test checks actual Shadow DOM clicks and host-driven reset.
43
+
44
+ Known limits: facade method captures are not revoked; bridge property errors have
45
+ no new diagnostic callback; constructor and initial `connectedCallback` events may
46
+ precede bridge listeners, while setter events caused by a bridge snapshot are
47
+ delivered after the listener is attached; store snapshot/value read protocols are
48
+ not unified. Browser-specific FACE and hydration evidence must still come from each
49
+ renderer's existing gates.
50
+
51
+ Packed ESM and CJS type checks run in separate strict programs. Importing both
52
+ Lit UI declaration graphs into a single TypeScript program currently conflicts
53
+ in `HTMLElementTagNameMap` because the generated element classes are nominal.
54
+ This gate does not certify that mixed-declaration mode; it does not hide it with
55
+ `skipLibCheck` either.
@@ -0,0 +1,51 @@
1
+ # 웹 컴포넌트 공통 인터페이스 요구사항 검토
2
+
3
+ [English](interop-review.en.md) · [소유권·제약](element-interop.md)
4
+
5
+ 상태: Core subpath 설계를 로컬 구현에 채택했습니다. 공개 버전 조합·dependency floor·배포는 승인되지 않았습니다.
6
+
7
+ | 요구사항 | 공통 책임 / 검증 위치 |
8
+ | --- | --- |
9
+ | 소비자는 렌더러에 의존하지 않음 | `ElementBridgeContract`와 의미 중심 `CounterHandle`. Host 계약에는 Lit/Preact/Signal 타입 없음 |
10
+ | 기존 import·호출 방식 유지 | Preact root·`/react-bridge` facade, Lit 객체형·두 인자형 및 alias 유지 |
11
+ | 같은 Action/Ref로 두 구현 연동 | `example/src/pages/integrations/element-interop.contract.test.tsx`: 실제 두 렌더러를 같은 Host로 실행하고 Preact→Lit 교체 |
12
+ | 입력 검증·기존 유효 상태 보존 | Facade의 잘못된 입력은 throw하고 이전 확정 값 유지. 검증 정책은 컴포넌트 setter가 소유 |
13
+ | 요청과 확정의 권한 분리 | `requestIncrement()`는 동결된 `count-request`만 발생. Host가 확정 input을 다시 넣어야 상태 변경 |
14
+ | 프로그래밍 입력 echo 금지 | 초기 input·확정 input·reset은 요청 이벤트를 다시 발행하지 않음 |
15
+ | DOM·내부 Signal 비노출 | 명시적 allow-list만 Facade로 노출. Host Ref는 `input/getSnapshot/requestIncrement`만 보유. detach 후 facade 접근 실패 |
16
+ | 기본값·제거 규칙 일치 | 건드리지 않은 기본값 보존, bridge가 넣었던 값만 제거 시 초기화. explicit undefined는 대입 |
17
+ | 이벤트 수명 일치 | 공통 unit suite와 양쪽 bridge suite: handler identity·교체·StrictMode·unmount cleanup 검증 |
18
+ | 설치 후 선언도 공통 계약 유지 | `pnpm verify:element-interop`: 격리 설치된 ESM/CJS 선언, 잘못된 payload·내부 명령·DOM 접근의 음성 타입 검사 |
19
+ | Host의 단일 React 런타임 사용 | 공통 구현에 어댑터의 React 전달. 패키지별 개발용 React 버전이 달라도 hook dispatcher를 혼용하지 않음 |
20
+ | React 외 Host 수명 | `pnpm verify:element-hosts`: 재사용 가능한 typed Vue 3.5.44 directive·Svelte 5.57.2 action·Angular 20.3.34 standalone directive. 실제 템플릿 정·음성 타입 검사·JSDOM 수명·비활성 서버 shell 검증. 공개 어댑터·hydration·실브라우저 인증은 아님 |
21
+ | native 실브라우저 수명 | `pnpm verify:element-host-browser`: 같은 컴파일 소스·실제 framework app·trusted Shadow DOM 클릭·호스트별 17개 검사. 현재 ego Chromium에 한정하며 hydration/FACE/렌더러 조합은 보장하지 않음 |
22
+ | DOM/React 분리 | Node-only 기본 entry 선언·프레임워크 미설치 import. DOM binding은 event-before-setter·재진입 dispose·terminal/replayable cleanup 검사 |
23
+ | 프레임워크 런타임 결합 방지 | 공통 root는 React/Preact/Lit·HTMLElement 전역 없이 import. 두 UI 패키지가 서로의 렌더러를 의존하지 않음 |
24
+ | 배포 안전 | 기존 버전 유지. 공개 Core/UI 배포에는 새 export가 포함된 Core dependency floor·버전 조합 승인 필요 |
25
+
26
+ 이번 공통화는 **소비자와 Host 사이의 전달·명령 경계**입니다. 모든 컴포넌트를 같은
27
+ 기반 클래스로 만드는 작업이 아닙니다. 스타일 part·slot·접근성·폼 의미·연결 자원
28
+ 소유권·SSR/hydration·업무 검증은 각 컴포넌트 계약에 남깁니다. 시그니처가 같다는
29
+ 이유만으로 업무 의미까지 같다고 판단하지 않습니다. fixture처럼 같은 의미 계약을
30
+ 명시적으로 채택한 구현끼리만 대체 가능합니다.
31
+
32
+ 기존 오류 정책은 구분해 보존합니다. Preact는 property 대입 오류를 throw하고 Lit는
33
+ best-effort로 처리합니다. 제거 시 cleanup은 양쪽 모두 best-effort입니다. 공통 구현에
34
+ 어댑터 정책을 명시적으로 전달하여 서로 다른 실패 의미를 암묵적으로 합치지 않습니다.
35
+ Preact의 기본값 보존·listener 재사용 개선은 후보 검증 근거이지 patch release 승인이 아닙니다.
36
+
37
+ 실브라우저 검토에서 기존 Preact showcase가 property를 선언하고도 accessor를 구현하지
38
+ 않은 문제도 확인했습니다. stepper/badge에 검증·입력 echo 방지를 갖춘 typed
39
+ `value/min/max/count` accessor를 추가하고 실제 Shadow DOM 클릭과 Host reset을 테스트합니다.
40
+
41
+ 남는 한계: 저장한 bound method는 revoke되지 않습니다. bridge property 오류에 대한
42
+ 새 진단 callback은 없고, 생성자와 최초 `connectedCallback` 이벤트는 bridge listener
43
+ 보다 먼저 발생할 수 있습니다. 반면 bridge snapshot이 일으킨 setter 이벤트는
44
+ listener를 먼저 연결한 뒤 전달됩니다. Store의 snapshot/value 읽기 계약도 통합하지
45
+ 않았습니다. FACE·hydration의 실브라우저 보장은 각 렌더러의 기존 게이트에서 별도로
46
+ 확인해야 합니다.
47
+
48
+ Packed ESM/CJS 타입 검사는 각각 독립적인 strict program에서 실행합니다. 현재 Lit UI의
49
+ 두 선언 그래프를 하나의 TypeScript program으로 함께 가져오면 nominal element class의
50
+ `HTMLElementTagNameMap` 선언이 충돌합니다. 이 혼합 모드를 보장한다고 주장하지 않으며,
51
+ `skipLibCheck`로 오류를 숨기지도 않습니다.