creo 0.2.5 → 0.2.7

package/AGENTS.md

@@ -0,0 +1,156 @@
+# Agent Guide for Creo
+
+## What is Creo?
+
+Creo is an imperative UI framework with virtual DOM. No JSX — views are function calls (`div()`, `text()`, `span()`). State is reactive (`use()`, `store`). Reconciliation uses Vue 3-style keyed diffing with LIS.
+
+## Project Layout
+
+```
+packages/creo/                   — Core creo framework
+  src/internal/engine.ts         — Core: reconciler, dirty queue, render loop
+  src/internal/internal_view.ts  — ViewRecord type, flags, structural comparison
+  src/internal/orchestrator.ts   — Tracks current active engine
+  src/public/view.ts             — view() factory, ViewBody, Slot types
+  src/public/state.ts            — State, Reactive, Use types
+  src/public/store.ts            — Store (global reactive state)
+  src/public/app.ts              — createApp() entry point
+  src/public/primitives/         — HTML element factories (div, span, text, etc.)
+  src/public/primitive.ts        — $primitive symbol, EventHandlerProps
+  src/render/html_render.ts      — DOM renderer (event delegation, attribute diffing)
+  src/render/json_render.ts      — JSON AST renderer (testing)
+  src/render/string_render.ts    — HTML string renderer (SSR)
+  src/render/render_interface.ts — IRender<Output> interface
+  src/functional/lis.ts          — Longest Increasing Subsequence (keyed reconciliation)
+  src/functional/shallow_equal.ts — Object comparison (no Object.keys allocation)
+packages/creo-router/            — Hash-based router (separate package)
+packages/creo-create-app/        — CLI scaffolding tool
+packages/creo-create-tauri-app/  — CLI scaffolding tool (Tauri)
+scripts/version.ts               — Version bump orchestrator
+scripts/publish.ts               — Build + publish orchestrator
+```
+
+## Key Architecture Decisions
+
+### ViewRecord is a plain object (not pooled)
+Views are GC'd objects with direct parent pointers (`view.parent: Maybe<ViewRecord>`). Children are arrays (`view.children: Maybe<ViewRecord[]>`). No arena allocator, no numeric IDs, no linked lists.
+
+### Composites have no DOM footprint
+Unlike React (which doesn't either) or the old creo (which used comment nodes), composite views set `renderRef = true` as a mounted marker. No DOM nodes are created for composites.
+
+### Primitives store `{ element, prevProps }` as renderRef
+The `kind` discriminant was removed. Use `view.flags & F_PRIMITIVE` to distinguish primitives from composites.
+
+### Slot children (sc) are pre-collected
+When a view has a slot, `newView()` calls `#collect(slot, [], res)` to eagerly evaluate the slot and store results in `view.sc`. This enables structural comparison (`hasScStructuralChange`) without re-running the slot.
+
+### scHost optimization
+Composites that receive a slot track `view.scHost` — the primitive whose `.children` contains the live slot children. When slot children have prop changes but identical structure, `#propagateScProps` updates live children directly, skipping the composite's reconcile.
+
+### preCollectedSc
+`#patchOrReplace` passes `pendView.sc` to `nextProps` as `preCollectedSc`, avoiding double slot evaluation. The sc items get re-parented to the old view.
+
+### Event delegation
+HTML renderer uses Inferno-style delegation: one listener per event type on the container element. Handlers are stored on elements via `Symbol.for("creo.ev")`. Zero closures per element — handler mapping happens at dispatch time.
+
+### textContent shortcut
+When a primitive has a single text child, the renderer sets `element.textContent` directly instead of creating a Text node. The text child gets `F_TEXT_CONTENT` flag.
+
+### Dispose optimization
+When a primitive with DOM is disposed, its children go through `#disposeVirtual` (skips `renderer.unmount`) since removing the parent element removes all descendants from DOM automatically.
+
+## Flags (internal_view.ts)
+
+```
+F_PENDING      = 1      — View not yet initialized (body is null)
+F_DIRTY        = 1 << 1 — Needs reconcile + render
+F_MOVED        = 1 << 2 — Position changed, needs DOM repositioning
+F_PRIMITIVE    = 1 << 3 — Is an HTML element/text, not a composite
+F_TEXT_CONTENT = 1 << 4 — Text rendered via parent's textContent
+```
+
+## Render Loop Flow
+
+```
+markDirty(view) → add to #dirtyQueue Set → schedule()
+                                              ↓
+render() processes #dirtyQueue:
+  for each view in Set (visits items added during iteration):
+    1. initViewBody(view) — if F_PENDING, call viewFn once
+    2. isNew = !view.renderRef
+    3. if F_DIRTY:
+       a. reconcile(view) — collect pending children, diff with old
+       b. renderer.render(view) — mount or update DOM
+       c. clear F_DIRTY, F_MOVED
+    4. else (F_MOVED only):
+       a. renderer.render(view) — reposition DOM
+       b. clear F_MOVED
+  #dirtyQueue.clear()
+  fire deferred callbacks (onMount, onUpdateAfter)
+```
+
+## Reconciliation Algorithm
+
+### Non-keyed
+Position-based: `old[i]` paired with `pending[i]`. Same viewFn → `nextProps`. Different → dispose + init. Extras disposed or mounted.
+
+### Keyed (Vue 3-style)
+1. **Head sync** — match from start while keys equal
+2. **Tail sync** — match from end while keys equal
+3. **Simple cases** — pure insertion or pure removal
+4. **Middle diff** — build `newKeyToIndex` map, compute `newIdxToOldIdx`, find LIS. Views in LIS stay; others get `markMoved`.
+
+## Testing
+
+```bash
+bun test packages/creo/src/                          # All tests
+bun test packages/creo/src/render/render.spec.ts     # Renderer + state tests
+bun test packages/creo/src/internal/                 # Virtual DOM correctness
+bun test packages/creo/src/render/benchmark.spec.ts  # Performance benchmarks
+```
+
+Tests use happy-dom for DOM simulation. The benchmark tests validate correctness of create/update/swap/select/remove/clear/replace operations on 1000-row tables.
+
+## Common Patterns When Modifying
+
+### Adding a new primitive
+Add to `packages/creo/src/public/primitives/primitives.ts`:
+```ts
+export const myTag = html<HtmlAttrs & { myProp?: string }, ContainerEvents>("my-tag");
+```
+Export from `packages/creo/src/index.ts`.
+
+### Changing the engine
+- `packages/creo/src/internal/engine.ts` is the core — reconciler, dirty queue, render loop
+- After changes, run `bun test packages/creo/src/` (all tests must pass)
+- Test with `cd docs && bun run dev` and open the playground recipes (simple-todo, advanced-todo, table, chess) for visual verification
+
+### Changing the HTML renderer
+- `html_render.ts` — DOM operations, event delegation, attribute diffing
+- `findParentDom(view)` walks parent chain for nearest primitive element
+- `findInsertionPoint(view)` scans siblings + recurses up for composites
+- After changes, verify with both todo and router examples
+
+## Conventions
+
+### `_` for Empty Props
+Always use `_` (from `@/functional/maybe`, re-exported by `creo`) instead of `{}` when a primitive or view needs no props:
+```ts
+div(_, () => { ... });   // not div({}, () => { ... })
+h1(_, "Title");          // not h1({}, "Title")
+```
+
+### Inline Strings
+Prefer passing strings directly as slots instead of wrapping in `() => text(...)`. The engine auto-wraps strings into text nodes:
+```ts
+button({ on: { click: handler } }, "Click me");  // not () => text("Click me")
+li(_, "Item text");                         // not () => text("Item text")
+span({ class: "label" }, title);            // string variable works too
+```
+Use `text()` only for dynamic values or when mixing text with other elements inside a function slot.
+
+### Changing ViewRecord shape
+- Update type in `internal_view.ts`
+- Update `newView()` in `engine.ts` (initializes all fields)
+- Update `#disposeVirtual()` if new field needs cleanup
+- JSON/String renderers may need updates if they access the field

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# 0.2.7
+1. Add support for new api `dispose`
+2. Add `ref` to primitives (DOM element) and composite views (exposed API)
+3. Provider-side rename: `ctx.expose(...)` is now `ctx.ref(...)`, matching the consumer-side `ref` prop. `Expose<Api>` is now `RefSetter<Api>`.
+4. Event handlers move from flat `on*` props to a nested `on: { ... }` object — e.g. `button({ on: { click: handler } })`. Removes the per-prop `isEventProp` charCode scan from the renderer's hot path; the `on` object's reference identity short-circuits the event diff. `EventHandlerProps<>` is removed.
+5. Drop `mouseEnter` / `mouseLeave` — use `pointerEnter` / `pointerLeave`. PointerEvents already cover mouse, touch, and pen via the `pointerType` field, so the duplicate mouse-only events were dead weight.
+
+## Migration from 0.2.6
+
+### Event handlers: flat `on*` props → nested `on: { ... }` object
+
+Event names lose the `on` prefix and the leading-capital — they become the camelCase form already used in `ContainerEvents` / `FormEvents` / `MediaEvents` (`click`, `pointerDown`, `keyDown`, `volumeChange`, …).
+
+```ts
+// Before
+button({ class: "btn", onClick: handleClick }, "Save");
+input({
+  value: v.get(),
+  onInput: handleInput,
+  onKeyDown: handleKey,
+  onBlur: handleBlur,
+});
+details({ onToggle: (e) => log(e.open) }, () => summary(_, "more"));
+
+// After
+button({ class: "btn", on: { click: handleClick } }, "Save");
+input({
+  value: v.get(),
+  on: { input: handleInput, keyDown: handleKey, blur: handleBlur },
+});
+details({ on: { toggle: (e) => log(e.open) } }, () => summary(_, "more"));
+```
+
+Mapping table for every prop the framework defines:
+
+| Before        | After (key inside `on: { ... }`) |
+| ------------- | -------------------------------- |
+| `onClick`            | `click`            |
+| `onDblclick`         | `dblclick`         |
+| `onPointerDown`      | `pointerDown`      |
+| `onPointerUp`        | `pointerUp`        |
+| `onPointerMove`      | `pointerMove`      |
+| `onPointerCancel`    | `pointerCancel`    |
+| `onPointerEnter`     | `pointerEnter`     |
+| `onPointerLeave`     | `pointerLeave`     |
+| `onMouseEnter`       | use `pointerEnter` |
+| `onMouseLeave`       | use `pointerLeave` |
+| `onKeyDown`          | `keyDown`          |
+| `onKeyUp`            | `keyUp`            |
+| `onFocus`            | `focus`            |
+| `onBlur`             | `blur`             |
+| `onInput`            | `input`            |
+| `onChange`           | `change`           |
+| `onScroll`           | `scroll`           |
+| `onLoad`             | `load`             |
+| `onError`            | `error`            |
+| `onToggle`           | `toggle`           |
+| `onVolumeChange`     | `volumeChange`     |
+| `onPlay` / `onPause` / `onEnded` | `play` / `pause` / `ended` |
+| `onTimeUpdate`       | `timeUpdate`       |
+| `onLoadedMetadata`   | `loadedMetadata`   |
+| `onLoadedData`       | `loadedData`       |
+| `onCanPlay`          | `canPlay`          |
+| `onCanPlayThrough`   | `canPlayThrough`   |
+| `onDurationChange`   | `durationChange`   |
+| `onRateChange`       | `rateChange`       |
+| `onSeeking` / `onSeeked` | `seeking` / `seeked` |
+| `onStalled` / `onWaiting` | `stalled` / `waiting` |
+
+Only primitive event props move. Custom `on*` props you define on your own views (`TodoItem({ onEdit, onSave })`, etc.) are plain props — leave them as-is.
+
+**Optional perf tip.** If you hoist the events object once, the renderer skips the per-event diff via `prev.on === next.on`:
+
+```ts
+const events = { click: handleClick, pointerDown: handleDown };
+// inside render():
+button({ class: "btn", on: events }, "Save");
+```
+
+Inline `on: { ... }` still works; the renderer falls back to a sub-key diff, which is still cheap.
+
+### Exposing an API: `ctx.expose(api)` → `ctx.ref(api)`
+
+Pure rename — same semantics, same `applyRef` wiring. The provider verb now uses the same word as the consumer noun.
+
+```ts
+// Before
+const TextInput = view<{ placeholder: string }, { focus: () => void }>(
+  ({ props, expose }) => {
+    let el: HTMLInputElement | null = null;
+    expose({ focus: () => el?.focus() });
+    return {
+      render() {
+        input({
+          placeholder: props().placeholder,
+          ref: (e) => { el = e as HTMLInputElement; },
+        });
+      },
+    };
+  },
+);
+
+// After
+const TextInput = view<{ placeholder: string }, { focus: () => void }>(
+  ({ props, ref }) => {
+    let el: HTMLInputElement | null = null;
+    ref({ focus: () => el?.focus() });
+    return {
+      render() {
+        input({
+          placeholder: props().placeholder,
+          ref: (e) => { el = e as HTMLInputElement; },
+        });
+      },
+    };
+  },
+);
+```
+
+The `Expose<Api>` type export is now `RefSetter<Api>`.
+
+The consumer side is unchanged: `TextInput({ placeholder: "Email", ref: myRef })`.
+
+### Removed type exports
+
+- `Expose<Api>` → renamed to `RefSetter<Api>`
+- `EventHandlerProps<Events>` → removed. The replacement shape is just `{ on?: Partial<Events> }`, applied automatically by `PrimitiveProps<Attrs, Events>`.
+
+# 0.2.6
+
+1. Cache first mount render props for primitives
+2. Fix re-bounding event to primitives
+3. Fix old children slice handling to avoid incorrect data duplicity
+4. Support chainable state & store
+5. Improve child placement lookup performance from O(N) to O(1)
+6. Improve "live-DOM" value handling: value, mute, checked
+7. Make stores to use publicly visible symbol Symbol.for("creo.store")
+8. 

package/README.md

@@ -336,8 +336,10 @@ bun test packages/creo/src/    # Run tests
 bun run build                  # Build all packages
 bun run typecheck              # Type-check
 
-# Run examples:
-cd examples/todo && bun install && bun run dev
+# Run the docs site (with the live recipe playground — simple-todo, advanced-todo, table, chess, etc.):
+cd docs && bun install && bun run dev
+
+# Run a standalone example:
 cd examples/router && bun install && bun run dev
 
 # Version management:

package/dist/functional/key.d.ts

@@ -1,2 +1 @@
 export type Key = number | string;
-export declare function generateNextKey(): string;

package/dist/index.d.ts

@@ -1,20 +1,20 @@
 export { createApp } from "./public/app";
-export { view } from "./public/view";
-export type { ViewBody, ViewFn, Slot, SlotContent, PublicView } from "./public/view";
+export { view, applyRef } from "./public/view";
+export type { ViewBody, ViewFn, Slot, SlotContent, PublicView, Ref, RefCallback, RefObject, RefSetter, } from "./public/view";
 export type { Reactive, Use } from "./public/state";
 export { State } from "./public/state";
 export { Store, store, isStore } from "./public/store";
 export { $primitive } from "./public/primitive";
-export type { PrimitiveProps, EventHandlerProps } from "./public/primitive";
+export type { PrimitiveProps } from "./public/primitive";
 export { html, text, div, span, section, article, aside, nav, header, footer, main, address, hgroup, search, p, h1, h2, h3, h4, h5, h6, pre, code, em, strong, small, br, hr, a, blockquote, label, abbr, b, bdi, bdo, cite, data, dfn, i, kbd, mark, q, rp, rt, ruby, s, samp, sub, sup, time, u, varEl, wbr, del, ins, ul, ol, li, dl, dt, dd, table, thead, tbody, tfoot, tr, th, td, caption, colgroup, col, form, button, input, textarea, select, option, fieldset, legend, datalist, optgroup, output, progress, meter, img, video, audio, canvas, source, track, map, area, picture, iframe, embed, object, portal, svg, details, summary, dialog, menu, figure, figcaption, script, noscript, template, slot, } from "./public/primitives/primitives";
 export type { BaseEventData, PointerEventData, KeyEventData, InputEventData, FocusEventData, MediaEventData, ScrollEventData, LoadEventData, ErrorEventData, ToggleEventData, ContainerEvents, FormEvents, MediaEvents, DisclosureEvents, HtmlAttrs, } from "./public/primitives/primitives";
 export type { IRender } from "./render/render_interface";
 export { HtmlRender } from "./render/html_render";
 export { JsonRender } from "./render/json_render";
 export type { JsonNode } from "./render/json_render";
-export { HtmlStringRender, StringRender } from "./render/string_render";
+export { HtmlStringRender } from "./render/string_render";
 export { Engine, type Scheduler } from "./internal/engine";
-export { type Maybe, type None, type Just, just, withDefault, _ } from "./functional/maybe";
+export { type Maybe, type None, type Just, just, withDefault, _, } from "./functional/maybe";
 export type { Key } from "./functional/key";
 export { shallowEqual } from "./functional/shallow_equal";
 export { assertNever } from "./functional/assert";