tutuca 0.9.104 → 0.9.106

package/README.md

@@ -1,13 +1,13 @@
 # Tutuca
 
-Zero-dependency batteries included SPA framework.
+Batteries included SPA framework with a dependency-free browser bundle.
 
 - **Single file, no build, no dependencies, no setup** — a script tag is all you need
 - **Batteries included** — state management, side effects, automatic memoization, drag and drop, testing, CLI tooling, LLM skills and more
 - **Fits in your head** (and the context window)
 - **View source friendly** — step through the whole stack
 - **As much HTML as possible, as little JS as needed**
-- ~182KB minified, ~41KB brotli compressed
+- ~182KB minified, ~41KB brotli compressed (the core browser bundle; the dev build adds linting and test helpers)
 
 ## Quick Start
 
@@ -62,6 +62,30 @@ For an interactive walk-through with editable examples, see the
 </html>
 ```
 
+## Concepts at a Glance
+
+Each concept has a tutorial section with editable live examples:
+
+- **[Components & state](https://marianoguerra.github.io/tutuca/tutorial.html#basics)** —
+  typed `fields` with auto-generated mutators (`setCount`, `toggleOpen`, …),
+  views as pure functions of a single immutable state tree
+  ([state & updates](https://marianoguerra.github.io/tutuca/tutorial.html#state-and-updates))
+- **[Collections](https://marianoguerra.github.io/tutuca/tutorial.html#collections)** —
+  iterate with `@each`, filter with `@when`, paginate with `@loop-with`
+- **[Rendering components](https://marianoguerra.github.io/tutuca/tutorial.html#rendering-components)** —
+  compose with `<x render>`, multiple views per component, scoped styles
+- **[Component communication](https://marianoguerra.github.io/tutuca/tutorial.html#component-communication)** —
+  bubble events up the tree, send messages to a target, run async work with
+  request/response
+- **[Macros](https://marianoguerra.github.io/tutuca/tutorial.html#macros)** —
+  reusable markup fragments with parameters and slots
+- **[Escape hatches](https://marianoguerra.github.io/tutuca/tutorial.html#escape-hatches)** —
+  drag and drop, web components, raw HTML
+- **[Testing](https://marianoguerra.github.io/tutuca/tutorial.html#testing)** —
+  `getTests()` suites run by the CLI or in the browser, plus a
+  [linter](https://marianoguerra.github.io/tutuca/tutorial.html#linter-reference)
+  that catches template mistakes before they render blank
+
 ## CLI
 
 Tutuca ships a single-file CLI (`dist/tutuca-cli.js`) for inspecting, linting,
@@ -92,9 +116,9 @@ tutuca help [command]
 | `list <module> [name] [--limit n]` | List components and their fields/views (`--limit n` caps, `0` = all) |
 | `examples <module> [--limit n]` | List the examples defined in the module's section (`--limit n` caps, `0` = all) |
 | `show <module> [name]` | Component API docs — all, or one by name |
-| `lint <module> [name]` | Run lint checks — all, or one by name (exit 2 on errors) |
-| `render <module> [name] [--title t] [--view v]` | Render examples to HTML |
-| `test <module> [name] [--grep p] [--bail]` | Run `getTests()` (exit 4 on failures) |
+| `lint <module> [name]` | Run lint checks — all, or one by name (exit `2` on errors) |
+| `render <module> [name] [--title t] [--view v]` | Render examples to HTML (exit `3` on render crash) |
+| `test <module> [name] [--grep p] [--bail]` | Run `getTests()` (exit `4` on failures) |
 | `storybook [dir]` | Serve a live storybook, auto-discovering co-located `*.dev.js` modules (`--port`, `--out`, `--dry-run`, `--no-margaui`, `--no-check`, `--no-tests`; no module path needed) |
 | `feedback [message]` | Append a feedback note (positional or stdin) to `~/.tutuca/feedback.jsonl` (no module path needed) |
 | `install-skill [--user\|--project] [--margaui-skill\|--immutable-skill\|--all] [--dot-agents] [--dry-run] [--force]` | Install bundled Claude Code skills (no module path needed) |
@@ -102,15 +126,11 @@ tutuca help [command]
 
 Global flags: `--json`, `-f, --format <cli\|md\|json\|html>`, `-o, --output <file>`, `--pretty`, `--module <path>`, `-h, --help`.
 
-Exit codes:
-
-- `0` — success
-- `1` — usage error (bad args, missing module, bad module shape)
-- `2` — `lint` reported errors
-- `3` — `render` crashed while rendering
-- `4` — `test` reported failures
-
-Errors carry stable codes (`ERR_USAGE_*`, `ERR_FORMAT_*`, `ERR_SKILL_*`) and "did you mean" suggestions for unknown commands and flags. Under `--json`, errors are emitted as a single-line JSON envelope on stderr.
+`storybook` wires [MargaUI](https://github.com/marianoguerra/margaui) — a
+Tailwind v4 / daisyUI-compatible class library — by default; `--no-margaui`
+skips it. For the full flag reference, error codes, and "did you mean"
+behavior, run `tutuca help <command>`, or `tutuca agent-context` for a
+machine-readable schema of the whole surface.
 
 ### Usage examples
 
@@ -124,27 +144,12 @@ npx tutuca show ./src/components.js Button --format md -o docs/button.md
 # Render every example to HTML, pretty-printed
 npx tutuca render ./src/components.js --format html --pretty -o dist/examples.html
 
-# Render a single named example
-npx tutuca render ./src/components.js Button --title "Disabled state"
-
-# Lint just one component (exit 2 if findings)
-npx tutuca lint ./src/components.js Button
-
 # Post-edit verification: lint, then render the example covering the
 # feature you just changed.
 npx tutuca lint ./src/components.js
 npx tutuca render ./src/components.js --title "Disabled state"
 ```
 
-### Wrapping
-
-The invocation stays short even without wrapping, but common patterns:
-
-- **`package.json` scripts** — `"docs": "tutuca show ./src/components.js"`
-- **Shell alias** — `tut() { npx tutuca "$1" ./src/components.js "${@:2}"; }`, then `tut render Button`
-- **`justfile` / `Makefile`** — one recipe per subcommand, passing through positionals
-- **Programmatic** — `import "tutuca/cli"` (the bundled entry) for custom build integration
-
 ## Use with Claude Code
 
 Tutuca ships an LLM-facing reference (`SKILL.md` plus topic files such as
@@ -160,7 +165,8 @@ npx tutuca install-skill
 # or user-scoped: writes ~/.claude/skills/tutuca/
 npx tutuca install-skill --user
 
-# pick a different bundled skill, or install all three
+# companion skills: MargaUI class lists, or Immutable.js (the values
+# tutuca state is made of) — or install all three
 npx tutuca install-skill --margaui-skill
 npx tutuca install-skill --immutable-skill
 npx tutuca install-skill --all
@@ -176,12 +182,12 @@ The skill content is generated from `docs/skill/`, so the same reference
 runs locally (`tutuca lint <module>` + `tutuca render <module> --title …`)
 and inside Claude.
 
-## License
-
-MIT
-
 ## Links
 
 - [Documentation & Playground](https://marianoguerra.github.io/tutuca/)
 - [Tutorial](https://marianoguerra.github.io/tutuca/tutorial.html)
 - [GitHub](https://github.com/marianoguerra/tutuca)
+
+## License
+
+MIT

package/dist/immutable.js

@@ -1952,21 +1952,10 @@ const Map = value => value === undefined || value === null ? emptyMap() : isMap(
 class MapImpl extends KeyedCollectionImpl {
   static {
     mixin(this, {
-      asImmutable,
-      asMutable,
-      deleteIn,
-      merge,
-      mergeWith,
-      mergeDeep,
-      mergeDeepWith,
-      mergeDeepIn,
-      mergeIn,
-      setIn,
-      update,
-      updateIn,
+      ...mutatorMethods(),
+      ...deepPathMethods(),
+      ...keyedMergeMethods(),
       wasAltered,
-      withMutations,
-      removeIn: deleteIn,
       concat: merge,
       [IS_MAP_SYMBOL]: true,
       [DELETE]: this.prototype.remove,
@@ -2748,6 +2737,32 @@ function mergeDeepIn(keyPath, ...iters) {
 function mixin(Class, methods) {
   Object.assign(Class.prototype, methods);
 }
+function mutatorMethods() {
+  return {
+    asImmutable,
+    asMutable,
+    withMutations
+  };
+}
+function deepPathMethods() {
+  return {
+    deleteIn,
+    removeIn: deleteIn,
+    mergeDeepIn,
+    mergeIn,
+    setIn,
+    update,
+    updateIn
+  };
+}
+function keyedMergeMethods() {
+  return {
+    merge,
+    mergeWith,
+    mergeDeep,
+    mergeDeepWith
+  };
+}
 const List = value => {
   const empty = emptyList();
   if (value === undefined || value === null) {
@@ -2774,17 +2789,9 @@ List.of = (...values) => List(values);
 class ListImpl extends IndexedCollectionImpl {
   static {
     mixin(this, {
-      asImmutable,
-      asMutable,
-      deleteIn,
-      mergeDeepIn,
-      mergeIn,
-      setIn,
-      update,
-      updateIn,
+      ...mutatorMethods(),
+      ...deepPathMethods(),
       wasAltered,
-      withMutations,
-      removeIn: deleteIn,
       [IS_LIST_SYMBOL]: true,
       [DELETE]: this.prototype.remove,
       merge: this.prototype.concat,
@@ -3319,6 +3326,8 @@ class OrderedMapImpl extends MapImpl {
       __iterate: CollectionImpl.prototype.__iterate
     });
   }
+  _map;
+  _list;
   constructor(map, list, ownerID, hash) {
     super(map ? map.size : 0, undefined, ownerID, hash);
     this._map = map;
@@ -3455,10 +3464,8 @@ Stack.of = (...values) => Stack(values);
 class StackImpl extends IndexedCollectionImpl {
   static {
     mixin(this, {
-      asImmutable,
-      asMutable,
+      ...mutatorMethods(),
       wasAltered,
-      withMutations,
       [IS_STACK_SYMBOL]: true,
       shift: this.prototype.pop,
       unshift: this.prototype.push,
@@ -3467,6 +3474,9 @@ class StackImpl extends IndexedCollectionImpl {
       [Symbol.iterator]: this.prototype.values
     });
   }
+  _head;
+  __ownerID;
+  __altered;
   constructor(size, head, ownerID, hash) {
     super();
     this.size = size;
@@ -3507,17 +3517,17 @@ class StackImpl extends IndexedCollectionImpl {
     return returnStack(this, newSize, head);
   }
   pushAll(iter) {
-    iter = IndexedCollection(iter);
-    if (iter.size === 0) {
+    const collection = IndexedCollection(iter);
+    if (collection.size === 0) {
       return this;
     }
-    if (this.size === 0 && isStack(iter)) {
-      return iter;
+    if (this.size === 0 && isStack(collection)) {
+      return collection;
     }
-    assertNotInfinite(iter.size);
+    assertNotInfinite(collection.size);
     let newSize = this.size;
     let head = this._head;
-    iter.__iterate(value => {
+    collection.__iterate(value => {
       newSize++;
       head = {
         value,
@@ -3554,7 +3564,7 @@ class StackImpl extends IndexedCollectionImpl {
     const newSize = this.size - resolvedBegin;
     let head = this._head;
     while (resolvedBegin--) {
-      head = head.next;
+      head = head?.next;
     }
     return returnStack(this, newSize, head);
   }
@@ -3572,7 +3582,7 @@ class StackImpl extends IndexedCollectionImpl {
     }
     return makeStack(this.size, this._head, ownerID, this.__hash);
   }
-  __iterate(fn, reverse) {
+  __iterate(fn, reverse = false) {
     if (reverse) {
       const arr = this.toArray();
       const size = arr.length;
@@ -3594,7 +3604,7 @@ class StackImpl extends IndexedCollectionImpl {
     }
     return iterations;
   }
-  __iterator(reverse) {
+  __iterator(reverse = false) {
     if (reverse) {
       const arr = this.toArray();
       const size = arr.length;
@@ -3660,8 +3670,8 @@ const Set = value => value === undefined || value === null ? emptySet() : isSet(
 Set.of = (...values) => Set(values);
 Set.fromKeys = value => Set(KeyedCollection(value).keySeq());
 Set.intersect = sets => {
-  sets = Collection(sets).toArray();
-  return sets.length ? Set(sets.pop()).intersect(...sets) : emptySet();
+  const setArray = Collection(sets).toArray();
+  return setArray.length ? Set(setArray.pop()).intersect(...setArray) : emptySet();
 };
 Set.union = sets => {
   const setArray = Collection(sets).toArray();
@@ -3670,9 +3680,7 @@ Set.union = sets => {
 class SetImpl extends SetCollectionImpl {
   static {
     mixin(this, {
-      withMutations,
-      asImmutable,
-      asMutable,
+      ...mutatorMethods(),
       [IS_SET_SYMBOL]: true,
       [DELETE]: this.prototype.remove,
       merge: this.prototype.union,
@@ -3680,6 +3688,8 @@ class SetImpl extends SetCollectionImpl {
       [Symbol.toStringTag]: "Immutable.Set"
     });
   }
+  _map;
+  __ownerID;
   constructor(map, ownerID) {
     super();
     this.size = map ? map.size : 0;
@@ -3720,7 +3730,7 @@ class SetImpl extends SetCollectionImpl {
     if (iters.length === 0) {
       return this;
     }
-    if (this.size === 0 && !this.__ownerID && iters.length === 1) {
+    if (this.size === 0 && !this.__ownerID && iters.length === 1 && !isOrdered(this)) {
       return Set(iters[0]);
     }
     return this.withMutations(set => {
@@ -3775,10 +3785,10 @@ function filterByIters(set, iters, shouldRemove) {
   if (iters.length === 0) {
     return set;
   }
-  iters = iters.map(iter => SetCollection(iter));
+  const sets = iters.map(iter => SetCollection(iter));
   return set.withMutations(s => {
     set.forEach(value => {
-      if (shouldRemove(value, iters)) {
+      if (shouldRemove(value, sets)) {
         s.remove(value);
       }
     });
@@ -3887,23 +3897,12 @@ const Record = (defaultValues, name) => {
 class RecordImpl {
   static {
     mixin(this, {
-      asImmutable,
-      asMutable,
-      deleteIn,
+      ...mutatorMethods(),
+      ...deepPathMethods(),
+      ...keyedMergeMethods(),
       getIn,
       hasIn,
-      merge,
-      mergeWith,
-      mergeDeep,
-      mergeDeepWith,
-      mergeDeepIn,
-      mergeIn,
-      setIn,
       toObject,
-      update,
-      updateIn,
-      withMutations,
-      removeIn: deleteIn,
       toJSON: toObject,
       [IS_RECORD_SYMBOL]: true,
       [DELETE]: this.prototype.remove,
@@ -4163,6 +4162,7 @@ const Repeat = (value, times) => {
   return new RepeatImpl(value, size);
 };
 class RepeatImpl extends IndexedSeqImpl {
+  _value;
   constructor(value, size) {
     super();
     this._value = value;
@@ -4199,7 +4199,7 @@ class RepeatImpl extends IndexedSeqImpl {
     }
     return -1;
   }
-  __iterateUncached(fn, reverse) {
+  __iterateUncached(fn, reverse = false) {
     const size = this.size;
     let i = 0;
     while (i !== size) {
@@ -4209,7 +4209,7 @@ class RepeatImpl extends IndexedSeqImpl {
     }
     return i;
   }
-  __iteratorUncached(reverse) {
+  __iteratorUncached(reverse = false) {
     const size = this.size;
     const val = this._value;
     let i = 0;
@@ -4247,7 +4247,7 @@ class RepeatImpl extends IndexedSeqImpl {
     this.prototype[Symbol.iterator] = this.prototype.values;
   }
 }
-const fromJS = (value, converter) => fromJSWith([], converter ?? defaultConverter, value, "", converter?.length > 2 ? [] : undefined, {
+const fromJS = (value, converter) => fromJSWith([], converter ?? defaultConverter, value, "", converter && converter.length > 2 ? [] : undefined, {
   "": value
 });
 function fromJSWith(stack, converter, value, key, keyPath, parentValue) {
@@ -4311,18 +4311,16 @@ function initCollectionConversions() {
   IndexedCollectionImpl.prototype.keySeq = function keySeq() {
     return Range(0, this.size);
   };
-  MapImpl.prototype.sort = function sort(comparator) {
-    return OrderedMap(sortFactory(this, comparator));
-  };
-  MapImpl.prototype.sortBy = function sortBy(mapper, comparator) {
-    return OrderedMap(sortFactory(this, comparator, mapper));
-  };
-  SetImpl.prototype.sort = function sort(comparator) {
-    return OrderedSet(sortFactory(this, comparator));
-  };
-  SetImpl.prototype.sortBy = function sortBy(mapper, comparator) {
-    return OrderedSet(sortFactory(this, comparator, mapper));
+  const patchSort = (Impl, OrderedCtor) => {
+    Impl.prototype.sort = function sort(comparator) {
+      return OrderedCtor(sortFactory(this, comparator));
+    };
+    Impl.prototype.sortBy = function sortBy(mapper, comparator) {
+      return OrderedCtor(sortFactory(this, comparator, mapper));
+    };
   };
+  patchSort(MapImpl, OrderedMap);
+  patchSort(SetImpl, OrderedSet);
 }
 var version$1 = "7.0.0";
 var pkg = {