tutuca 0.9.82 → 0.9.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.82",
+  "version": "0.9.84",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -13,6 +13,7 @@
     "./ext": "./dist/tutuca.ext.js",
     "./extra-ext": "./dist/tutuca-extra.ext.js",
     "./dev-ext": "./dist/tutuca-dev.ext.js",
+    "./storybook": "./dist/tutuca-storybook.js",
     "./immutable": "./dist/immutable.js",
     "./chai": "./dist/chai.js",
     "./package.json": "./package.json"
@@ -40,7 +41,9 @@
     "stresstest": "bun scripts/stresstest.js",
     "smoke-test": "bun tools/tutuca.js lint ./test/todo.js && bun tools/tutuca.js render ./test/todo.js && bun tools/tutuca.js test ./test/todo.js && bun tools/tutuca.js lint ./test/json.js && bun tools/tutuca.js render ./test/json.js"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./deps/chai.js"
+  ],
   "files": [
     "dist/tutuca.js",
     "dist/tutuca.min.js",
@@ -52,6 +55,7 @@
     "dist/tutuca.ext.js",
     "dist/tutuca-extra.ext.js",
     "dist/tutuca-dev.ext.js",
+    "dist/tutuca-storybook.js",
     "dist/immutable.js",
     "dist/chai.js",
     "skill"

package/skill/tutuca/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tutuca
-description: Use when authoring or reviewing tutuca modules — `component({...})` definitions, `html`...`` views, `@`-directives, `input` / `bubble` / `receive` / `response` / `alter` handlers, macros, or `getTests` exports — or when running the `tutuca` CLI (`lint` / `test` / `render` / `docs`). Covers the post-edit `tutuca <module> lint` → `test` → `render --title "<example>"` verification recipe.
+description: Use when authoring or reviewing tutuca modules — `component({...})` definitions, `html`...`` views, `@`-directives, `input` / `bubble` / `receive` / `response` / `alter` handlers, macros, or `getTests` exports — or when running the `tutuca` CLI (`lint` / `test` / `render` / `show`). Covers the post-edit `tutuca lint <module>` → `test` → `render --title "<example>"` verification recipe.
 ---
 
 <!-- Source of truth: docs/skill/. The skill/tutuca/ copy is generated by scripts/build-skill.js — edit docs/skill/, not skill/. -->
@@ -9,7 +9,7 @@ description: Use when authoring or reviewing tutuca modules — `component({...}
 
 Tutuca is an immutable-state SPA framework. See [core.md](./core.md)
 for the framework primer and the post-edit verification recipe
-(`tutuca <module> lint` → `test` → `render --title "<example>"`).
+(`tutuca lint <module>` → `test` → `render --title "<example>"`).
 
 ## Companion skills
 

package/skill/tutuca/advanced.md

@@ -165,8 +165,8 @@ import { SEQ_INFO } from "tutuca";
 class MyClass {
   // ...
 }
-MyClass.prototype[SEQ_INFO] = (seq, visit) => {
-  for (const [k, v] of seq.entries()) visit(k, v, "data-sk");
+MyClass.prototype[SEQ_INFO] = (seq, visit, start, end) => {
+  for (const [k, v] of seq.entries()) visit(k, v, "sk");
 };
 ```
 
@@ -175,8 +175,18 @@ is shared across module graphs (source vs. bundled tutuca). The
 renderer reads `seq[SEQ_INFO]` directly (no `.constructor` lookup),
 which is why the walker goes on the prototype, not as a static.
 
-The third arg to `visit` is the data attribute used for stable-key
-diffing (typically `"data-sk"` for "sequence key").
+The third arg to `visit` must be `"sk"` (keyed entries) or `"si"`
+(positional indexes): it is the meta key event-path reconstruction
+reads to resolve an event back to its entry — any other value means
+`@key` and keyed steps silently stop resolving inside `@each`.
+
+`start`/`end` are an optional `[start, end)` slice produced by
+`@loop-with` (Array.slice semantics). Walkers may ignore them, in
+which case `@loop-with` ranges simply don't apply to that type.
+
+See `docs/examples/custom-collection.js` for a complete worked
+example: an immutable keyed list whose walker supports slicing and
+whose entries resolve `@key` in event handlers.
 
 ## Tailwind / MargaUI Class Compilation (extra build)
 

package/skill/tutuca/cli.md

@@ -42,6 +42,7 @@ Use `--module=<path>` if the path conflicts with positional parsing.
 | `test <module> [name]`   | Run tests defined by `getTests({ describe, test, expect })`. Filter by component name, `--grep <pattern>`, or `--bail`. Exits **4** on any failure |
 | `help [cmd]`             | Show usage. No module path needed                                                                                      |
 | `feedback [message]`     | Append a feedback note (positional or stdin) to `~/.tutuca/feedback.jsonl`. No module path needed                      |
+| `install-skill [name]`   | Copy a bundled skill (`tutuca`, `margaui`, `immutable-js`, or `--all`) into `.claude/skills/`. No module path needed   |
 | `agent-context`          | Print a versioned JSON schema of every command, flag, exit code, and error code. No module path needed                 |
 
 ## Global flags

package/skill/tutuca/component-design.md

@@ -119,7 +119,7 @@ A compact worked version of the first four (`method`, `bubble`, `send`/`receive`
   → [advanced.md](./advanced.md) "Pitfall: `@if.class` payloads are invisible to
   the scanner", and the worked decoy view in `personal-site.js`.
 
-- **Do close the loop after every change** with `tutuca <module> lint` → `test` →
+- **Do close the loop after every change** with `tutuca lint <module>` → `test` →
   `render`. → [core.md](./core.md) "Verifying changes"
 
 ## Smells & refactors

package/skill/tutuca/core.md

@@ -977,6 +977,17 @@ export function getExamples()         {
 export function getTests({ describe, test, expect }) { /*...*/ }      // optional — see cli.md
 ```
 
+Best practice: have `getComponents()` return **every** component the module
+defines — child and helper components included — and give each one at least
+one item in `getExamples()`. A component left out of `getComponents()` is
+invisible to `tutuca lint`/`render`/`test`, so it silently loses linting and
+render coverage. If your components already live behind a differently named
+export, alias it instead of teaching tools a new name:
+
+```js
+export { allMyComponents as getComponents } from "./app.js";
+```
+
 ## See also
 
 - [component-design.md](./component-design.md) — design judgment for shaping a

package/skill/tutuca/patterns/README.md

@@ -36,6 +36,7 @@ task.
 
 - [Bind text and attributes](bind-text-and-attributes.md) — `@text`, `:attr`, `$'…'` templates, scope enrichment.
 - [Handle events](handle-events.md) — `@on.<event>`, handler args, modifiers, custom events.
+- [Read a picked file](file-input.md) — `@on.change="… event"` and reading `event.target.files`.
 
 ## Component communication
 

package/skill/tutuca/patterns/file-input.md

@@ -0,0 +1,39 @@
+# Read a picked file
+
+**Problem:** let the user pick a file and show its metadata.
+
+```js
+component({
+  name: "FilePicker",
+  fields: { name: "", size: 0, type: "", hasFile: false },
+  input: {
+    // `event` is the raw DOM event; the File is on event.target.files
+    onPickFile(event) {
+      const file = event.target.files?.[0];
+      if (!file) return this.setHasFile(false);
+      return this.setName(file.name)
+        .setSize(file.size)
+        .setType(file.type)
+        .setHasFile(true);
+    },
+  },
+  view: html`<section>
+    <input type="file" @on.change="onPickFile event" />
+    <p @hide=".hasFile">No file selected yet.</p>
+    <dl @show=".hasFile">
+      <dt>Name</dt><dd @text=".name"></dd>
+      <dt>Size</dt><dd @text=".size"></dd>
+      <dt>Type</dt><dd @text=".type"></dd>
+    </dl>
+  </section>`,
+});
+```
+
+Pass `event` (not `value`) to the handler: for a file input `value` is just the
+fake `C:\fakepath\…` string, while `event.target.files` holds the real `File`
+objects. The metadata (`name`/`size`/`type`/`lastModified`) is available
+synchronously; the *contents* are not — read those with the async `File` API
+(`file.text()`, `file.arrayBuffer()`) and feed the result back in through a
+`request`/`response` or a follow-up `send`. Flatten what you need into fields so
+the view can bind each piece; gate the summary on a `hasFile` flag with
+`@show`/`@hide`.