@tschk/moonshine-vue 0.0.0-stage → 0.4.49

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.
package/README.md CHANGED
@@ -1,3 +1,522 @@
1
- # Temporary Holding Version
1
+ # `@tschk/moonshine-vue`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The legacy `/vue` and `/compiler-sfc` entries re-export Vue as a peer.
4
+ At runtime, the root bridges and independent `/reactive` entry depend only on Moonshine's
5
+ signal kernel and native DOM package. They import no Vue, React, WASM, or Crepus
6
+ runtime. Vue remains an optional peer for the two legacy entries.
7
+
8
+ Strict TypeScript checking of the root entry requires installing
9
+ `@tschk/moonshine-framework`, even when importing only a bridge: the root also
10
+ exports `crepusRenderer` with the framework's `Renderer` contract. The framework
11
+ remains optional for runtime imports and bridge-only browser/Bun/Node bundles.
12
+ This requirement does not apply to the signal-only `@tschk/moonshine` core entry.
13
+
14
+ The native entry is a bounded composition API implementation. It is not a
15
+ replacement for Vue's component/compiler ABI: do not alias `vue` wholesale onto
16
+ this package or execute existing Vue compiler output against it.
17
+
18
+ ```ts
19
+ import { fromMoonshineSignal } from "@tschk/moonshine-vue";
20
+ import { ref } from "@tschk/moonshine-vue/reactive";
21
+ ```
22
+
23
+ | Subpath | Provides |
24
+ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25
+ | `.` | signal bridges, lazy native SSR compatibility renderer |
26
+ | `./vue` | `vue` runtime re-exports |
27
+ | `./compiler-sfc` | `vue/compiler-sfc` re-exports |
28
+ | `./reactive` | native `ref`/`shallowRef`/`customRef`/`triggerRef`/`useTemplateRef`/`useModel`/`createModel`/`useId` (`ModelRef`, `DefineModelOptions`), `toRef`/`toRefs`/`unref`/`toValue`/`isRef`, `reactive`/`shallowReactive`/`readonly`/`shallowReadonly`, `isReactive`/`isReadonly`/`isShallow`/`isProxy`/`toRaw`/`markRaw`, `computed`, `watch`/`watchSyncEffect`/`onWatcherCleanup` (`WatchHandle`), `effectScope`/`getCurrentScope`/`onScopeDispose` |
29
+ | `./context` | native component `provide`, `inject`, `hasInjectionContext`, `useId` |
30
+ | `./lifecycle` | native component `onBeforeMount`, `onMounted`, `onBeforeUnmount`, `onUnmounted`, `onErrorCaptured` (`ErrorCapturedHook`) |
31
+ | `./text` | native DOM and SSR interpolation conversion |
32
+ | `./props` | compiler-facing shallow declared props and owned parent refresh |
33
+ | `./events` | compiler-facing typed component callbacks, callback arrays and per-instance once delivery |
34
+ | `./normalize` | native class/style normalization and compiler-facing DOM/SSR policies |
35
+ | `./expose` | compiler-facing `exposeRefs`, `bindRef`, `bindComponentRef`, and `useTemplateRef` for `defineExpose` and template refs |
36
+ | `./app` | native `createApp` returning `{ mount, unmount }` where `mount(target)` returns the root's exposed instance |
37
+
38
+ `./framework` exports the same lazy `crepusRenderer` compatibility name as the
39
+ root. Its optional `@tschk/moonshine-framework` peer is needed only when rendering.
40
+ Pages must use explicit `@tschk/moonshine-dom/ssr` server factories. Existing
41
+ React IR pages need to be ported; this facade does not render React components.
42
+ The compatibility root renderer loads source files under Bun. Bundled deployments use
43
+ `@tschk/moonshine-dom/framework-native` with their bundled module table.
44
+
45
+ Legacy peer: `vue` >= 3, needed only for `/vue` and `/compiler-sfc`.
46
+
47
+ Native `watch` requires `{ flush: "sync" }` and supports `immediate`, `deep`
48
+ (`boolean` or finite depth `number`), `once`, reactive object sources (deep by
49
+ default for `reactive`, depth `1` by default for `shallowReactive` or
50
+ `{ deep: false }`), `onWatcherCleanup(fn, failSilently?)`, and `WatchHandle`
51
+ (`stop()`, `pause()`, `resume()`, and callable `handle()`). Component
52
+ pre/post render scheduling and Vue Map/WeakMap/WeakSet collection proxies are
53
+ not implemented by this entry. Plain objects and
54
+ arrays are reactive; nested refs unwrap on object properties and retain their
55
+ identity at integer array entries.
56
+ Each watcher run can register multiple cleanup callbacks (via the callback's
57
+ third parameter or `onWatcherCleanup`). Reruns and stops drain
58
+ them in registration order, attempt all callbacks after a failure, and preserve
59
+ the first error. A cleanup that stops its watcher prevents another callback run.
60
+
61
+ ### Native Set tracking
62
+
63
+ `reactive(new Set())`, `shallowReactive(new Set())`, `readonly(new Set())`,
64
+ `shallowReadonly(new Set())`, deep refs containing Sets and Sets nested in plain state
65
+ use the independent native graph. Membership reads track individual keys;
66
+ size, iteration and `forEach` track membership changes. Duplicate additions,
67
+ missing deletions and empty clears do not notify. Object entries retain
68
+ raw/proxy membership identity and wrap on iteration in deep `reactive`/`readonly`; stored native refs retain
69
+ their identity. `shallowRef` keeps external Sets raw and tracks replacement only.
70
+ Map/WeakMap/WeakSet reactivity and Set algebra methods remain unsupported. Mutating an original raw Set bypasses notification.
71
+
72
+ The local compiler accepts unshadowed global `Set<T>` prop values. Local `Set`
73
+ bindings, including conservative checks in nested scopes, remain rejected until
74
+ full type-resolution metadata is available. The existing authored counter fixture grows by 730 gzip bytes with
75
+ this support; the default signal kernel remains unchanged. No speed claim.
76
+
77
+ ### Optional native watch errors
78
+
79
+ `./errors` exports `withComponentErrorHandler(handler, setup)`, which requires a
80
+ live native owner and scopes work created synchronously by `setup`. It handles
81
+ function-source getter errors, `watch` callbacks, `watchSyncEffect` bodies and each
82
+ registered watcher cleanup. The handler runs synchronously and untracked with the
83
+ original thrown value and `{ component, phase }`. The finite phase labels are
84
+ `"watch getter"`, `"watch callback"`, `"watch effect"` and `"watch cleanup"`.
85
+ `component` is the native frame or `undefined`, not a Vue public instance.
86
+ Getter/effect bodies keep their normal tracking; handled getter errors yield
87
+ `undefined`, and handled cleanup errors allow peers and the next run to continue.
88
+ Source reads do not restart recursively when getter reporting writes the source;
89
+ callback feedback remains synchronous and reentrant.
90
+
91
+ Returned promises with callable `then` and `catch` report rejection through the
92
+ captured handler/frame, including after owner disposal. A then-only object is
93
+ ignored. A throwing `.catch` method escapes its caller. A handler that throws
94
+ logs its secondary error once; genuine reentrant watch errors invoke it again.
95
+
96
+ Without this scope, existing native throwing and `catchError` behavior remains.
97
+ Other error phases retain their existing handling. This is not Vue's app
98
+ configuration or `onErrorCaptured`, and adds no watcher or component frame.
99
+
100
+ `toRef` preserves existing native refs, creates live writable property aliases,
101
+ and wraps getters in readonly refs without caching their results. Its optional
102
+ property default applies only to `undefined`; an alias does not make a plain
103
+ source object reactive. Function-valued properties and
104
+ defaults stay literal. `unref` unwraps native refs once and never calls functions;
105
+ `toValue` unwraps native refs and invokes zero-argument getter functions while
106
+ keeping `ref(fn)` function values literal.
107
+ `isRef` recognizes only this entry's native refs, including computed/getter/custom refs;
108
+ it does not accept Vue host refs or objects with a spoofed `__v_isRef` flag.
109
+
110
+ `shallowRef` stores raw values unchanged and tracks replacement of `.value` using
111
+ `Object.is` equality. It preserves existing native refs, existing reactive proxies,
112
+ and literal function values. Nested raw mutations do not notify automatically;
113
+ calling `triggerRef(ref)` forces subscribers (including `computed`, `watchSyncEffect`,
114
+ and synchronous `watch`) to re-evaluate after in-place mutations. `customRef((track, trigger) => ({ get, set }))`
115
+ creates a native ref with explicit dependency tracking and notification control.
116
+
117
+ `shallowReactive` tracks root-level object properties, array indices/length/mutations,
118
+ and `Set` membership without deep wrapping or nested ref unwrapping. `readonly`
119
+ creates a deep read-only view over plain objects, arrays, `Set`s, reactive proxies,
120
+ and refs (forwarding reactive tracking when wrapping a reactive target while throwing
121
+ `TypeError` on writes, deletes, `defineProperty`, or `Set` mutations); `shallowReadonly`
122
+ enforces read-only access only at the root level. `markRaw` marks an object or `Set`
123
+ so `reactive`, `shallowReactive`, `readonly`, `shallowReadonly`, and `ref` return it
124
+ unwrapped (both at root and nested positions), and `toRaw` unwraps any native proxy
125
+ layer back to the underlying raw object. `isReactive`, `isReadonly`, `isShallow`,
126
+ and `isProxy` inspect native proxy and ref flags.
127
+
128
+ `effectScope(detached?)`, `EffectScope`, `getCurrentScope()`, and `onScopeDispose(fn, failSilently?)`
129
+ manage grouped reactive ownership (`watch`, `watchSyncEffect`, `computed`, nested
130
+ non-detached `effectScope`s, and `onScopeDispose` callbacks). Non-detached scopes
131
+ attach to the enclosing active `EffectScope` or native component/root owner;
132
+ detached scopes (`effectScope(true)`) remain active until their own `.stop()` is called.
133
+ Inside native component initialization, `getCurrentScope()` and `onScopeDispose()`
134
+ bind to the component's scope and clean up on component unmount.
135
+
136
+ Native computed refs are lazy and cached, propagate previous successful values,
137
+ and keep writable setters. Stopping an owner releases its watchers without
138
+ freezing separately retained computed refs.
139
+
140
+ The local Crepuscularity compiler now lowers the bounded typed setup counter
141
+ through real DOM/SSR module graphs without Vue. It supports imported native
142
+ ref/computed helpers, stable function handlers, interpolation and live props;
143
+ strict public prop types and independent instances are verified. Inline and
144
+ imported finite prop interfaces support shallow local writes/deletes and
145
+ coalesced parent refresh. Scoped/module styles, entities, unsupported whitespace, dynamic
146
+ handlers, non-finite defaults and unsupported Boolean prop variants still diagnose. Nested Vue render
147
+ scheduling, effectful parent getter timing, general component composition and
148
+ the VNode ABI remain incomplete. These compiler changes are local and unreleased.
149
+
150
+ The local compiler also accepts ordinary props-less `<script setup>` components,
151
+ including empty setup, constants, JavaScript/TypeScript counters and imported
152
+ children. It supplies an empty props type when no props macro is present, after
153
+ the existing macro, import and async-setup validation. Components that declare
154
+ typed props keep their existing contract. This removes an unnecessary
155
+ `defineProps` declaration; it adds no attrs fallthrough, Options API or host VNode
156
+ support. The compiler work is unpublished. Set
157
+ `MOONSHINE_CREPUS_COMPILER` to the local compiler to enable the isolated source
158
+ regression in `test/standalone.test.ts`.
159
+
160
+ The local compiler lowers text and numeric input/textarea `v-model` to the opt-in
161
+ `./model` DOM factory and `./model/ssr` server factory. Plain models and `.lazy`,
162
+ `.trim`, `.number` use the independent graph, including IME composition handling,
163
+ focused trimming, empty numeric strings and owner cleanup. Writable setup
164
+ `ref`/`shallowRef` targets and member targets rooted in setup refs or `reactive`
165
+ objects are supported. Input types must be static text, search, tel, url, email,
166
+ password, number or range; textarea children and explicit value/defaultValue
167
+ conflicts reject. Static checkbox/radio models also compile locally: scalar typed
168
+ true/false values, loose array membership in click order, identity-based Sets,
169
+ programmatic Set updates and listener cleanup use independent factories.
170
+ Checked-model modifiers and file models remain unsupported,
171
+ as do dynamic types and readonly/unknown targets. Source lowering
172
+ is local and unpublished; this does not implement Vue directives or hydration.
173
+
174
+ Checked models match eleven direct browser cases and thirteen authored SFC phases
175
+ against Vue 3.5.13. Source SSR follows Vue's distinct root/nested policy: empty
176
+ Sets are truthy on the server, while DOM Set membership is identity-based;
177
+ nested scalar models use `true-value`, while root fallthrough SSR uses scalar
178
+ truthiness. Explicit checked attributes remain meaningful. Repeated Bun and
179
+ minified Node SSR compare all structure, attributes and text, ignoring only
180
+ attribute order and equivalent checked-attribute spelling. This is mount/SSR
181
+ support, without hydration. The existing counter bundle has no size change;
182
+ the compared form workload is 9,957 gzip bytes native versus 21,855 for Vue.
183
+ These are fixture sizes, without a startup or runtime speed claim.
184
+
185
+ Native `./select` supports single/multiple select models with inline options and
186
+ optgroups, typed option values, `.number`, Array/Set outputs and owner cleanup.
187
+ Undefined models do not adopt authored defaults. Arrays use loose membership;
188
+ Sets retain identity. Accepted writes preserve the user's duplicate option choice;
189
+ later authored component updates reconcile selection through the existing Vue
190
+ scheduler. Typed option updates and programmatic Set changes remain reactive.
191
+ `./select/ssr` follows source SSR selection, including duplicate selected options,
192
+ null models with omitted option values, and distinct Set behavior. It does not
193
+ infer an omitted option value from its label on the server. These DOM/SSR
194
+ policies intentionally differ, matching the compared Vue source behavior.
195
+
196
+ The local Crepus compiler supplies the select/option factories and writable-target
197
+ checks. Other select modifiers, nested selects, component-supplied options and
198
+ non-option markup in selects reject. Hydration remains unsupported. Eight direct
199
+ Chromium cases, eleven source SSR cases, thirteen actual SFC browser phases, repeated fresh Bun/minified Node SSR and both source
200
+ and declaration-consumer type lanes pass. The existing counter bundle stays
201
+ unchanged. This select fixture is 11,722 gzip bytes versus Vue 3.5.13's 21,900;
202
+ there is no startup/runtime speed claim. Compiler changes remain unpublished.
203
+
204
+ Plain component `v-model` compiles locally when the imported Vue SFC child declares
205
+ `modelValue` in typed props and `update:modelValue` in typed emits, or declares
206
+ `defineModel`. It uses the
207
+ existing live props and event protocol, with no added runtime or dependencies.
208
+ Explicit update listeners retain template attribute order relative to the setter;
209
+ `.once` listeners preserve the distinct DOM/server policies. Readonly targets,
210
+ conflicting explicit model props/listeners and missing child contracts reject.
211
+ Static named and multiple models also compile locally: identifier/kebab arguments
212
+ normalize to canonical child prop names, each with a matching declared update
213
+ event. Listener order is tracked separately for each model. Model props named
214
+ `class` and `style` use the existing component normalizers. Dynamic model arguments
215
+ remain unsupported. Component modifiers compile locally as described
216
+ below. This is source support, not Vue's compiled component ABI or hydration.
217
+
218
+ `@tschk/moonshine-vue/reactive` exports `useModel(props, name, options?)`,
219
+ compiler-facing `createModel`, `ModelRef<T, M, G, S>`, and
220
+ `DefineModelOptions<T, G, S>`. Top-level `const` `defineModel` declarations
221
+ (including `const [model, modifiers] = defineModel<T, M>(...)` and
222
+ `const [model, modifiers] = useModel(props, name, options)`) lower in the local
223
+ Crepus compiler to `createModel`, augmenting the component's public TypeScript
224
+ props type with the model prop (`required` when `{ required: true }` without
225
+ `default`), modifier prop (`modelModifiers`/`modelValueModifiers` or
226
+ `<name>Modifiers`), and `EventListeners<{ "update:<name>": [value: T] }>` while
227
+ registering child `defineModel` metadata for parent `v-model` and boolean-cast
228
+ validation. `createModel` / `useModel` support static and cached factory
229
+ defaults (running factories within the component consumer context for `inject()`
230
+ and preserving function defaults when the model type is a sole function),
231
+ Boolean prop casting, custom `get` and `set` transforms (with normalization
232
+ force-trigger when `set` normalizes an assigned value back to the current model
233
+ value), standalone local state when the parent omits `v-model`, controlled
234
+ parent props, and SSR reads/writes.
235
+
236
+ Thirteen authored parent/child browser phases compare both listener orders,
237
+ `.once`, external parent updates, multiple instances and disposal against Vue
238
+ 3.5.13. Server setup emits are compared across repeated fresh Bun/minified Node
239
+ renders; both source and declaration consumers pass in tsc/tsgo, including invalid
240
+ prop and callback payload checks. Before emit modifier support, this default-model
241
+ fixture was 10,510 gzip bytes versus Vue's 21,104. No startup/runtime speed claim; compiler changes remain
242
+ local and unpublished.
243
+
244
+ The named-model fixture adds fourteen browser phases covering distinct payloads,
245
+ kebab arguments, per-model listener order, `.once`, class/style normalization,
246
+ multiple roots and disposal. Repeated Bun/minified Node SSR setup emits and both
247
+ source/declaration type lanes pass. Before emit modifier support, its production
248
+ browser bundle was 10,983 gzip bytes versus Vue 3.5.13's 21,335 for the same fixture; this is no timing claim.
249
+ These compiler changes remain local and unpublished.
250
+
251
+ Component modifiers now compile locally through the opt-in event protocol.
252
+ `.trim` maps string arguments; `.number` converts every original emitted argument
253
+ with `parseFloat`, retaining the original value on NaN. When both flags are set,
254
+ number conversion uses the original arguments, including their whitespace.
255
+ Regular and once listeners receive the same converted arguments. Custom flags
256
+ are available to children that declare the corresponding modifier prop; they do
257
+ not change payloads automatically. Flag order is preserved and repeated flags
258
+ collapse. Bare models add no modifier object. Explicit `v-model:modelValue.trim`
259
+ passes `modelValueModifiers`, unlike plain `v-model.trim`'s `modelModifiers`,
260
+ preserving Vue's distinct behavior. Empty and `__proto__` modifiers reject.
261
+
262
+ Nine authored cases pass nineteen Chromium phases and repeated fresh
263
+ Bun/minified Node SSR comparisons against Vue 3.5.13. Source and declaration
264
+ consumers pass both typecheckers. Undeclared modifier props still reach the raw
265
+ emitter; Vue's extra root DOM attribute is omitted because native attrs
266
+ fallthrough remains unsupported. Modifier objects have stable identity per native
267
+ component instance. Mutating a modifier object after a parent model update differs
268
+ from Vue: native emits observe that mutation, while Vue emits use the new render's
269
+ raw modifier object. This mutation pattern is not compatible yet. This
270
+ fixture is 10,943 gzip bytes versus Vue's 21,493. The unchanged named-model control
271
+ adds 158 gzip bytes for emit conversion (11,141 versus its previous 10,983);
272
+ the signal kernel stays unchanged. No startup/runtime speed claim. Compiler
273
+ changes remain local and unpublished; dynamic model arguments and hydration
274
+ remain unsupported.
275
+
276
+ Native `./context` provides `provide`, `inject`, `hasInjectionContext`, `useId`, and typed
277
+ `InjectionKey` symbols during synchronous native component initialization (`./reactive` also re-exports `useId`). Injection
278
+ searches ancestors, never the same component's own providers. Nearest ancestors
279
+ shadow outer values, including explicitly provided `undefined`; refs stay refs.
280
+ Defaults are values unless the third argument is `true`, which invokes a missing
281
+ value's factory untracked. Factories have no Vue public-instance `this` receiver.
282
+ `useId()` generates deterministic tree-scoped IDs (`v-0`, `v-1`, ...) scoped to the
283
+ root owner of the component/render/SSR tree so DOM and SSR produce identical IDs
284
+ without cross-request or cross-instance counter state.
285
+ Outside initialization, `provide`/`inject`/`useId` throw; `hasInjectionContext` returns false.
286
+ This supports DOM and SSR component scopes, not Vue app-level injection or
287
+ `app.runWithContext`, and does not establish full SFC compiler compatibility.
288
+
289
+ ### Optional native lifecycle
290
+
291
+ `@tschk/moonshine-vue/lifecycle` exports `onBeforeMount`, `onMounted`, `onBeforeUnmount`,
292
+ `onUnmounted`, `onErrorCaptured`, and `ErrorCapturedHook`. Register synchronously during native component initialization,
293
+ register `onMounted`/`onBeforeUnmount`/`onUnmounted` inside an `onBeforeMount` callback, or
294
+ register `onUnmounted` inside an `onMounted` or `onBeforeUnmount` callback.
295
+ SSR skips `onBeforeMount`, `onMounted`, `onBeforeUnmount`, and `onUnmounted` (`onErrorCaptured` remains active in both DOM and SSR for setup/watch error propagation).
296
+ `onBeforeMount` hooks run synchronously as each component's setup finishes before its template nodes are attached to the parent DOM container and before `onMounted` hooks flush.
297
+ Mounted hooks run after synchronous children and DOM commits,
298
+ with pending component references published first. Disposed components skip queued
299
+ mounts. Before-unmount hooks run parent first with DOM and watchers still active;
300
+ unmounted hooks run child first after DOM removal and reactive teardown. Callbacks
301
+ are untracked; returned cleanup functions are ignored. Mounted callbacks flush
302
+ pending references first, recheck that the owner is live, then invoke the hook
303
+ with its component context. Before-mount, mounted, and before-unmount callbacks restore the previous
304
+ context even when they throw. Registration from an already disposed owner,
305
+ including an unmounted callback, is rejected.
306
+ `onErrorCaptured(hook)` intercepts descendant component errors (synchronous or asynchronous `watch` getter/callback/effect/cleanup errors and descendant lifecycle hook errors) bottom-up across the native component hierarchy (`hook(err, instance, info)` runs untracked in the capturing ancestor's injection context; returning `false` stops further propagation and prevents unhandled rethrow).
307
+
308
+ This optional entry has no Vue dependency. It does not provide Vue public-instance
309
+ receivers, app lifecycle, update hooks, async component/Suspense scheduling, or
310
+ full SFC compatibility. Crepus lowers named/aliased imports of these five hooks
311
+ in the accepted authored source slice. Permanent DOM/SSR fixtures verify nested
312
+ registration, connected mount/before phases, disconnected child-first cleanup,
313
+ two instances and server callback suppression. Intrinsic and imported component
314
+ template refs (`ref="x"` and `:ref="'x'"` targeting top-level `const` `ref`,
315
+ `shallowRef`, or `useTemplateRef` setup declarations) publish before `onMounted` hooks run and clear
316
+ to `null` on unmount. Vue's full error-handler policy remains unproven. A failed
317
+ native mounted hook tears down its owner; the reference can retain the subtree
318
+ until unmount.
319
+
320
+ Callback failures propagate after pending peers and disposal finish.
321
+
322
+ A watch started under an already disposed native owner throws. Ownerless watches
323
+ remain manually stoppable.
324
+
325
+ `./reactive` also exports `watchSyncEffect(effect)` and
326
+ `onWatcherCleanup(cleanupFn, failSilently?)`, with `watch` and `watchSyncEffect`
327
+ returning a `WatchHandle` (`stop()`, `pause()`, `resume()`, and callable
328
+ `handle()`). The effect runs immediately and tracks synchronous reads, including
329
+ conditional sources. Its supplied cleanup registrar and `onWatcherCleanup`
330
+ accept multiple callbacks while active; registrations after stopping are ignored
331
+ in `watchSyncEffect` and run immediately in `watch`. Calling `onWatcherCleanup`
332
+ outside an active watcher execution (or inside a `watch` source getter or
333
+ cleanup function) throws unless `failSilently` is `true`. Cleanup runs untracked
334
+ before reruns and on stop. Writes made by the effect or its cleanup do not
335
+ recursively invoke that same effect; cleanup writes remain visible to the
336
+ following run. `pause()` suspends callback/effect reruns while retaining tracked
337
+ dependencies, and `resume()` synchronously flushes if any tracked dependency
338
+ changed while paused. Native owners stop their effects on disposal; ownerless
339
+ effects require manual stopping. SSR sync effects run and stop with the request
340
+ owner. Promise continuations are not tracked.
341
+
342
+ Cleanup attempts every registered callback and propagates the first failure;
343
+ failed effect runs release their registered cleanup while preserving the effect
344
+ error. This follows native error handling rather than Vue's app error handler.
345
+ This entry does not supply scheduled `watchEffect` / `watchPostEffect` or a Vue
346
+ component render scheduler.
347
+
348
+ `./reactive` exports `toRefs(object)` for destructuring linked properties without
349
+ losing live reads or writes. It snapshots enumerable string keys (including
350
+ inherited keys), omits symbols and preserves array length and holes. Properties
351
+ added later need `toRef(object, key)`. Existing native refs retain their identity.
352
+ Getter/setter descriptors keep their source receiver; writes to getter-only
353
+ properties throw. This does not implement Vue readonly-proxy warnings or SFC
354
+ compilation.
355
+
356
+ `./text` exports `toDisplayString` for DOM interpolation and
357
+ `toDisplayStringSSR` for SSR. Both preserve Vue's conversion of nullish values,
358
+ native refs, arrays, objects, maps, sets and symbols without invoking function
359
+ values. DOM conversion can return `undefined` when an object's `toJSON` does;
360
+ SSR converts that result to the literal string `"undefined"`. These helpers
361
+ produce text, and the renderer handles HTML escaping. This optional entry adds
362
+ no host dependency and does not establish Vue SFC or VNode compatibility.
363
+
364
+ Reactive object and array property updates use `Object.is`: writing negative
365
+ zero after positive zero notifies, while repeating NaN does not. Nested values
366
+ and accessor setter receivers retain this policy. This is specific to the Vue
367
+ entry; native `createMutable` keeps strict equality by default.
368
+
369
+ `./props` exports compiler-facing `createProps(source, declaredKeys)` and
370
+ `createServerProps(source, declaredKeys)`. Initial props are shallow snapshots
371
+ with own optional keys, preserving nested objects and functions. DOM local
372
+ writes/deletes are reactive; later parent changes coalesce in one owned
373
+ microtask, and unchanged final parent values preserve local overrides. Nested
374
+ props refreshes drain in that same microtask in setup order, so a queued child
375
+ sees its parent's final snapshot. Disposal drops pending refreshes. Server
376
+ snapshots remain independent per request.
377
+ The compiler resolves finite declared keys through its existing safe module
378
+ resolver; unresolved shapes diagnose rather than guessing keys.
379
+
380
+ Imported PascalCase child components now have real CLI DOM/SSR source proof for
381
+ explicit props-only calls. Parent and child snapshots settle in one props
382
+ microtask in either enqueue order while retaining child state, nodes and focus.
383
+ The permanent source gate includes two independent instances and fresh escaped
384
+ SSR requests. Static default slots have the separate source proof below. Typed component events now have separate real CLI DOM/SSR and production browser proof; the permanent source gate includes these cases. Attrs fallthrough remains unsupported. The bounded lifecycle imports above have separate source proof.
385
+ Native disposal removes retained-node
386
+ listeners; Vue can still invoke a listener on a saved detached button.
387
+
388
+ This props-only queue does not implement Vue's nested renderer jobs, `nextTick`
389
+ or immediate DOM timing. Parent getters are observed synchronously; local DOM
390
+ effects retain native timing. Setter failures preserve the first error and
391
+ allow sibling refresh/retry, deliberately avoiding the reference's cleanup bugs.
392
+
393
+ Assigning a reactive child back into a parent preserves its identity and raw
394
+ storage, including array entries and mutation methods. Deep refs, shallow refs,
395
+ and reactive properties all use `Object.is` replacement equality.
396
+
397
+ Plain unscoped Vue CSS now travels as inventoried build assets through the normal
398
+ Bun stylesheet output and SSR route links. Repeated component instances share
399
+ the stylesheet; whitespace-only blocks emit no assets. The 458-module source
400
+ gate covers unchanged CSS bytes, strict generated types, browser colors and
401
+ fresh escaped SSR. No Vue runtime is imported for this path.
402
+
403
+ Scoped/module CSS, preprocessors, external styles, URLs, imports, escapes and
404
+ `v-bind` CSS still reject. The graph reader uses Bun's CSS parser and reads only
405
+ the declared inventory; this does not claim PostCSS validation parity.
406
+
407
+ The optional compiler-private `./slots` entry supports implicit static default
408
+ content and static default outlets. Authored source tests verify repeated
409
+ outlets, lazy fallback, child consumer injection, live parent values, child prop
410
+ refresh, retained leaf state/focus and independent instances through DOM and SSR.
411
+ DOM content owns one attached scope for cache lifetime and failed-factory
412
+ rollback; it adds no component frame. Ordinary Vue modules import no slot helper.
413
+
414
+ The shared permanent gate covers 734 generated modules and all 728 emitted
415
+ TypeScript modules under both strict checkers using frozen combined
416
+ compiler `82e517ca`. Named/scoped/dynamic slots still reject.
417
+ Native granular updates skip unrelated fallback function calls that Vue
418
+ component jobs repeat; those call-count traces deliberately differ. This does
419
+ not supply Vue's component render scheduler or promise full ABI compatibility.
420
+
421
+ The optional `/events` helper lowers inline typed tuple-map `defineEmits` declarations and stable parent `@event` handlers, including `.once`. Declared props exclude event callbacks. DOM callbacks stop with their component owner; SSR callbacks remain callable after rendering, matching the bounded reference cases. Native DOM updates and error routing retain Moonshine semantics. Event validators, model events, arbitrary event names and attrs fallthrough still diagnose. This does not establish Vue scheduler or compiler ABI compatibility.
422
+
423
+ Declared component class/style props now retain literal versus expression provenance in Crepus. The optional `/normalize` entry handles nested class values, static declaration strings, dynamic styles and reactive object cloning with separate DOM/SSR policies. Fresh actual Vue 3.5.13 comparisons pass Unicode whitespace, falsy values, constant aliases, proxy identity, narrow typed styles, retained local state/focus, cleanup and two fresh SSR renders. Intrinsic dynamic class/style, undeclared fallthrough and other directives remain separate work. Merged `__proto__` style keys are safe own data properties; this intentionally differs from the reference prototype setter.
424
+
425
+ Boolean-bearing finite `defineProps` types now use compiler-only
426
+ `createBooleanProps` / `createServerBooleanProps` from `/props`; ordinary props
427
+ use their original exports and omit the resolver from bundles. The compiler
428
+ retains Boolean/String union order, distinguishes absence from explicit
429
+ undefined, accepts proven declared ASCII hyphen aliases and precasts empty/name
430
+ literals without widening public prop types. Pure optional Boolean setup values
431
+ are internally required; mixed unions remain optional. Fresh source graphs pass
432
+ both strict checkers for both targets and actual Vue 3.5.13 Chromium/SSR comparisons.
433
+
434
+ Duplicate canonical/alias bindings, ambiguous Boolean intersections, literal
435
+ hyphen declarations mixed with casts, Boolean id/class/style declarations,
436
+ non-ASCII nonempty name-literal casts remain explicit gaps.
437
+ Finite defaults have separate shallow readonly typing; full Vue render jobs and broader macro typing remain incomplete.
438
+
439
+ ### Compiler-facing defaults
440
+
441
+ The optional `/props` entry includes `createDefaultProps`,
442
+ `createServerDefaultProps`, `DefaultValues`, and `withVueScheduler` for native
443
+ compiler integration. The finite default tuples specify literal values versus
444
+ factories. Factories receive each instance's stable raw props object, run in its
445
+ consumer context, and cache successful results including `undefined`. Setup
446
+ props are shallow readonly in TypeScript; the caller's props remain optional
447
+ where declared. These helpers do not install runtime readonly proxies.
448
+
449
+ The component carrier gates render work while defaults prepare. Successful
450
+ preparation refreshes that component's render callbacks; failed preparation
451
+ keeps its previous DOM until a later successful parent props commit. Independent
452
+ child component groups remain live. It reuses existing native owners and DOM
453
+ controls and guards feedback at 1,000 render or post waves. Ordinary native DOM
454
+ rendering remains synchronous without the carrier.
455
+
456
+ Finite typed source `withDefaults` now has real CLI, strict caller, Chromium and
457
+ fresh SSR acceptance, including ordered factories, cached undefined, Boolean
458
+ fallbacks and failed refresh recovery. Spreads, accessors, setup-value captures,
459
+ nested macros and unresolved default shapes still diagnose. Outer casts and
460
+ satisfies constraints retain their type checks.
461
+
462
+ This is a compiler-private contract, not Vue's complete component job or app
463
+ error policy. Render-expression evaluation and fallback, props-job error
464
+ attribution, and full Vue lifecycle timing remain separate work. The optional `/errors` scope handles watch phases; it does not
465
+ turn a default factory failure into an app error handler call.
466
+
467
+ ### Compiler-facing expose and template refs
468
+
469
+ `@tschk/moonshine-vue/expose` exports `exposeRefs(exposed)` and its
470
+ `ShallowUnwrap<T>` type helper, `bindRef`, `bindComponentRef`, and re-exports
471
+ `useTemplateRef` and `TemplateRef<T>` from `@tschk/moonshine-vue/reactive`.
472
+ `exposeRefs` returns a shallow-unwrapping proxy for `defineExpose(record)` where
473
+ top-level native refs (`ref`, `shallowRef`, `computed`, `toRef`,
474
+ `useTemplateRef`) unwrap on `get` and forward `set` to writable `.value`
475
+ (throwing `TypeError` on readonly refs), while plain values, getters/setters and
476
+ reactive objects retain their descriptors and prototype checks. When a `<script setup>`
477
+ component omits `defineExpose` or calls `defineExpose()`, it exposes an empty
478
+ null-prototype object (`exposeRefs({})`) so component template refs receive a
479
+ non-null exposed instance rather than leaking internal setup bindings.
480
+
481
+ `useTemplateRef<T>(key)` requires active component initialization and a unique
482
+ non-empty string key per component instance, returning a `TemplateRef<T>`
483
+ (`Readonly<Ref<T | null>>`) initialized to `null` whose user `.value = ...`
484
+ setter throws `TypeError` while internal `bindRef` / `bindComponentRef` bindings
485
+ publish and clear the reference.
486
+
487
+ The local Crepus compiler lowers top-level `defineExpose` and static template
488
+ refs (`ref="x"` and `:ref="'x'"` targeting a top-level `const` `ref`,
489
+ `shallowRef`, or `useTemplateRef("x")` setup binding) on intrinsic elements
490
+ (including `<input>`, `<textarea>`, `<select>`, and `<option>` with `v-model`)
491
+ and imported PascalCase components. Intrinsic refs bind through `bindRef` and
492
+ component refs bind through `componentRef` (or `bindComponentRef` for
493
+ `useTemplateRef` targets) with `cleanup: "commit"`, publishing before `onMounted`
494
+ hooks run and clearing to `null` on unmount. In SSR, `defineExpose` runtime
495
+ evaluation and template `ref` attributes are erased while preserving the
496
+ component's `ComponentView<Node, Exports, Props>` return brand. Dynamic ref
497
+ expressions, function refs, and `v-for` ref arrays remain explicit compile errors.
498
+
499
+ ### Optional native application mount
500
+
501
+ `@tschk/moonshine-vue/app` exports `createApp(component, props)` and the
502
+ `ComponentExports<C>` type helper for native component factories, including
503
+ Crepus-compiled Vue components. Props retain the factory's public type. The
504
+ returned native application has `mount(target)` and `unmount()`; `mount` returns
505
+ the root component's exposed value (`ComponentExports<typeof component>`, or a
506
+ null-prototype empty object when nothing is exposed), not a full Vue public
507
+ instance (`$el`, `$props`, `$emit`).
508
+
509
+ `mount` accepts a selector, Element or ShadowRoot in the current DOM realm,
510
+ clears its existing children and mounts one owned root. A private container lease
511
+ rejects another app before clearing and remains held until teardown finishes.
512
+ Invalid targets leave
513
+ DOM unchanged and allow a corrected attempt. Once rendering starts, a failed or
514
+ successful attempt is terminal; mounting again throws. `unmount` is idempotent;
515
+ before mounting it is a no-op, and during synchronous mounting it requests
516
+ cleanup when that mount finishes. Failed setup/mounting and rejected promise or
517
+ VNode results release owned work. Accessor children retain native tracking.
518
+
519
+ This entry adds no Vue scheduler group, VNode renderer, Options API, application
520
+ configuration, public instance, runtime template compiler or hydration. Use native
521
+ factories and native DOM children; the separate legacy `/vue` and `/compiler-sfc`
522
+ entries and their optional peer are unchanged.
package/package.json CHANGED
@@ -1,6 +1,64 @@
1
1
  {
2
2
  "name": "@tschk/moonshine-vue",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.49",
4
+ "description": "Native composition helpers and signal bridges with optional legacy Vue runtime/compiler entries",
5
+ "license": "ISC",
6
+ "type": "module",
7
+ "main": "./src/index.ts",
8
+ "types": "./src/index.ts",
9
+ "exports": {
10
+ ".": "./src/index.ts",
11
+ "./vue": "./src/vue.ts",
12
+ "./reactive": "./src/reactive.ts",
13
+ "./compiler-sfc": "./src/compiler-sfc.ts",
14
+ "./framework": "./src/framework.ts",
15
+ "./context": "./src/context.ts",
16
+ "./lifecycle": "./src/lifecycle.ts",
17
+ "./text": "./src/text.ts",
18
+ "./model": "./src/model.ts",
19
+ "./model/ssr": "./src/model-ssr.ts",
20
+ "./select": "./src/select.ts",
21
+ "./select/ssr": "./src/select-ssr.ts",
22
+ "./props": "./src/props.ts",
23
+ "./slots": "./src/slots.ts",
24
+ "./events": "./src/events.ts",
25
+ "./normalize": "./src/normalize.ts",
26
+ "./errors": "./src/errors.ts",
27
+ "./expose": "./src/expose.ts",
28
+ "./app": "./src/app.ts"
29
+ },
30
+ "dependencies": {
31
+ "@tschk/moonshine": "^0.4.48",
32
+ "@tschk/moonshine-dom": "^0.4.48"
33
+ },
34
+ "devDependencies": {
35
+ "typescript": "7.0.2"
36
+ },
37
+ "peerDependencies": {
38
+ "vue": ">=3",
39
+ "@tschk/moonshine-framework": "^0.4.48"
40
+ },
41
+ "peerDependenciesMeta": {
42
+ "vue": {
43
+ "optional": true
44
+ },
45
+ "@tschk/moonshine-framework": {
46
+ "optional": true
47
+ }
48
+ },
49
+ "files": [
50
+ "src",
51
+ "README.md"
52
+ ],
53
+ "keywords": [
54
+ "moonshine",
55
+ "vue",
56
+ "adapter"
57
+ ],
58
+ "scripts": {
59
+ "format": "bunx prettier --check .",
60
+ "lint": "bunx oxlint .",
61
+ "typecheck": "bunx tsc --noEmit",
62
+ "test": "bun test"
63
+ }
64
+ }