humn 1.6.1 → 1.7.0

package/.cursor/rules/humn.mdc

@@ -0,0 +1,20 @@
+---
+description: Use this rule when working with Humn frontend framework code (.humn files, Cortexes).
+globs: ["*.humn", "src/**/*.js", "src/**/*.ts"]
+---
+
+# Humn
+
+Humn is a reactive frontend framework. It uses `.humn` files and Cortex state.
+
+## Rules
+
+- Humn is NOT React, Vue, Svelte, or Solid.
+- Do not use React hooks, JSX, Svelte `$:` syntax, or Solid signals.
+- Do not start fetches directly in the `<script>` block. It runs on every render. Use `onMount()` instead.
+- Use `resource()` and `resourceSynapse()` for async data fetching.
+- Use `.humn` files for components. They contain `<script>`, template markup, and `<style>`.
+- Use `Cortex` for state management, with `memory` for state and `synapses` for actions.
+- Read state via `cortex.memory`, mutate via `cortex.synapses` which calls `set((state) => ...)`.
+- Component styles inside `<style>` are automatically scoped.
+- Instantiate Cortex with an object: `new Cortex({ memory: {...}, synapses: (set) => ({...}) })`.

package/AGENTS.md

@@ -0,0 +1,64 @@
+# Humn project instructions
+
+This project uses Humn.
+
+## Commands
+
+- Install: `npm install`
+- Dev server: `npm run dev`
+- Build: `npm run build`
+- Tests: `npm test` if present
+
+## Humn conventions
+
+- Components use `.humn` files.
+- A `.humn` file may contain `<script>`, template markup and `<style>`.
+- Component styles are scoped.
+- Shared state should live in Cortexes.
+- Do not start fetches or side effects directly in the `<script>` block. It runs on every render. Use `onMount()`.
+- Use `resource()` and `resourceSynapse()` for async server state.
+- Read state from `cortex.memory`.
+- Change state through `cortex.synapses`.
+- Use `persist(initial, { key })` for localStorage-backed state.
+- Do not use React hooks, JSX component files, Svelte stores or Solid signals unless the project explicitly adds those libraries.
+
+## Cortex example
+
+```js
+import { Cortex, persist } from 'humn'
+
+export const uiCortex = new Cortex({
+  memory: {
+    activeView: persist('accounts', { key: 'active-view' }),
+  },
+
+  synapses: (set) => ({
+    setActiveView(view) {
+      set((state) => {
+        state.activeView = view
+      })
+    },
+  }),
+})
+```
+
+## Component example
+
+```html
+<script>
+  import { uiCortex } from './cortexes/uiCortex.js'
+
+  const { activeView } = uiCortex.memory
+  const { setActiveView } = uiCortex.synapses
+</script>
+
+<button onclick="{()" ="">
+  setActiveView('accounts')}> Current view: {activeView}
+</button>
+
+<style>
+  button {
+    border-radius: 8px;
+  }
+</style>
+```

package/CLAUDE.md

@@ -0,0 +1,64 @@
+# Humn project instructions
+
+This project uses Humn.
+
+## Commands
+
+- Install: `npm install`
+- Dev server: `npm run dev`
+- Build: `npm run build`
+- Tests: `npm test` if present
+
+## Humn conventions
+
+- Components use `.humn` files.
+- A `.humn` file may contain `<script>`, template markup and `<style>`.
+- Component styles are scoped.
+- Shared state should live in Cortexes.
+- Do not start fetches or side effects directly in the `<script>` block. It runs on every render. Use `onMount()`.
+- Use `resource()` and `resourceSynapse()` for async server state.
+- Read state from `cortex.memory`.
+- Change state through `cortex.synapses`.
+- Use `persist(initial, { key })` for localStorage-backed state.
+- Do not use React hooks, JSX component files, Svelte stores or Solid signals unless the project explicitly adds those libraries.
+
+## Cortex example
+
+```js
+import { Cortex, persist } from 'humn'
+
+export const uiCortex = new Cortex({
+  memory: {
+    activeView: persist('accounts', { key: 'active-view' }),
+  },
+
+  synapses: (set) => ({
+    setActiveView(view) {
+      set((state) => {
+        state.activeView = view
+      })
+    },
+  }),
+})
+```
+
+## Component example
+
+```html
+<script>
+  import { uiCortex } from './cortexes/uiCortex.js'
+
+  const { activeView } = uiCortex.memory
+  const { setActiveView } = uiCortex.synapses
+</script>
+
+<button onclick="{()" ="">
+  setActiveView('accounts')}> Current view: {activeView}
+</button>
+
+<style>
+  button {
+    border-radius: 8px;
+  }
+</style>
+```

package/README.md

@@ -10,19 +10,31 @@ While you can use `humn` standalone with the `h()` syntax, we recommend using it
 npm install humn
 ```
 
+## AI & Agent Support
+
+Humn includes built-in instructions to help AI coding agents (like Cursor, Claude Code, GitHub Copilot) understand its conventions and write idiomatic code.
+
+To initialize the AI instructions in your project, run:
+
+```bash
+npx humn init-ai
+```
+
+This will create `AGENTS.md`, `CLAUDE.md`, and `.cursor/rules/humn.mdc` in your workspace, ensuring coding agents don't confuse Humn with React or Svelte.
+
 ## Quick Start with `h()`
 
 Here's a simple counter example using the `h()` syntax.
 
-### 1. Create a Cortex (Store)
+### 1. Create a Cortex (Cortex)
 
 The `Cortex` holds your application's state (`memory`) and the actions that can modify it (`synapses`).
 
 ```javascript
-// store.js
+// cortex.js
 import { Cortex } from 'humn'
 
-export const counterStore = new Cortex({
+export const counterCortex = new Cortex({
   memory: {
     count: 0,
   },
@@ -46,11 +58,11 @@ Components are functions that return a tree of `h()` calls.
 ```javascript
 // App.js
 import { h } from 'humn'
-import { counterStore } from './store'
+import { counterCortex } from './cortex'
 
 export function App() {
-  const { count } = counterStore.memory
-  const { increment, decrement } = counterStore.synapses
+  const { count } = counterCortex.memory
+  const { increment, decrement } = counterCortex.synapses
 
   return h('div', {}, [
     h('h1', {}, `Count: ${count}`),

package/bin/humn.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const pkgDir = path.resolve(__dirname, '..')
+
+const args = process.argv.slice(2)
+
+if (args[0] === 'init-ai') {
+  console.log('Initializing Humn AI guidance files...')
+
+  const destDir = process.cwd()
+
+  // Create .cursor/rules if needed
+  const cursorRulesDir = path.join(destDir, '.cursor', 'rules')
+  if (!fs.existsSync(cursorRulesDir)) {
+    fs.mkdirSync(cursorRulesDir, { recursive: true })
+  }
+
+  // Files to copy
+  const filesToCopy = [
+    { src: 'AGENTS.md', dest: 'AGENTS.md' },
+    { src: 'CLAUDE.md', dest: 'CLAUDE.md' },
+    { src: '.cursor/rules/humn.mdc', dest: '.cursor/rules/humn.mdc' },
+  ]
+
+  filesToCopy.forEach((file) => {
+    const srcPath = path.join(pkgDir, file.src)
+    const destPath = path.join(destDir, file.dest)
+
+    if (fs.existsSync(srcPath)) {
+      if (!fs.existsSync(destPath)) {
+        fs.copyFileSync(srcPath, destPath)
+        console.log(`✓ Created ${file.dest}`)
+      } else {
+        console.log(`! Skipped ${file.dest} (already exists)`)
+      }
+    } else {
+      console.warn(`? Source file ${file.src} not found in package.`)
+    }
+  })
+
+  console.log(
+    '\nAI context initialized! Agentic tools will now understand Humn conventions better.',
+  )
+} else {
+  console.log(`
+Usage: humn <command>
+
+Commands:
+  init-ai    Copy AI guidance files (AGENTS.md, CLAUDE.md, .cursor/rules) into your project
+  `)
+}

package/dist/cortex.d.ts

@@ -53,7 +53,7 @@ export class Cortex<MemoryType extends unknown, SynapsesType extends unknown> {
     synapses: SynapsesType;
     /**
      * Creates a copy-on-write mutation draft that tracks changed paths without
-     * cloning the whole store before every mutative update.
+     * cloning the whole cortex before every mutative update.
      */
     _createMutationDraft(base: any, changedPaths: any): {
         getNextState: () => any;