svelte-origin 1.0.0-next.48 → 1.0.0-next.49

package/LLM.md

@@ -1,540 +1,545 @@
-# svelte-origin - LLM Reference
-
-> Quick-reference documentation for LLM assistance with svelte-origin v3.0
-
-## Overview
-
-`svelte-origin` provides a macro-based system for defining reusable state + props + methods patterns in Svelte 5. Origins are factories that create reactive instances with props, state, derived values, and methods.
-
-**IMPORTANT**: This library uses **compile-time macros** (prefixed with `$`). These are transformed during build and do NOT exist at runtime.
-
----
-
-## The `$origin` Namespace
-
-All macros live under the `$origin` namespace:
-
-| Macro | Context | Description |
-|-------|---------|-------------|
-| `$origin({...})` | `.svelte.ts` files | Define an origin factory |
-| `$origin.props({...})` | Anywhere | Define props schema with defaults |
-| `$origin.component(Factory)` | ⚠️ `.svelte` only | Create origin from component `$props()` |
-| `$origin.create(Factory, {...})` | ✅ Everywhere | Programmatic origin creation with reactivity |
-| `$origin.bind(variable)` | Inside `$origin.create()` | Bind prop to existing reactive variable |
-| `$origin.for(Factory)` | ⚠️ `.svelte` only | Forward props to child origin/element |
-| `$origin.Props<typeof Factory>` | Type context | Extract component props type |
-| `$origin.Of<typeof Factory>` | Type context | Extract origin instance type |
-| `$bindable(value)` | Inside `$origin.props({})` | Mark a prop as two-way bindable |
-
-### Context Restrictions
-
-- ⚠️ **Component-only macros** (`$origin.component()`, `$origin.for()`): Using these in `.svelte.ts` or `.svelte.js` module files will throw a helpful compile-time error
-- ✅ **Universal macros** (`$origin.create()`, `$origin.props()`): Work in any context
-
----
-
-## Defining Origins (`.svelte.ts` files)
-
-Origins are defined in `.svelte.ts` files using the `$origin()` macro:
-
-```ts
-// counter.svelte.ts
-export const Counter = $origin({
-	props: $origin.props({
-		label: 'Counter',           // Default string
-		count: $bindable(0),        // Bindable number (two-way)
-		step: 1                     // Default number
-	}),
-
-	// Internal state (not exposed - prefix with _)
-	_history: [] as number[],
-
-	// Derived values (use getters + $derived)
-	get doubled() {
-		return $derived(this.props.count * 2)
-	},
-
-	// Methods
-	increment() {
-		this._history.push(this.props.count)
-		this.props.count += this.props.step
-	},
-
-	decrement() {
-		this._history.push(this.props.count)
-		this.props.count -= this.props.step
-	}
-})
-```
-
-### Key Rules for Origin Definitions
-
-1. **Use `this.props.*`** to access props (not `props.*`)
-2. **Use `$derived()`** for computed/derived values (must be inside a getter)
-3. **Use `$bindable(defaultValue)`** for two-way bindable props
-4. **Prefix with `_`** for internal/private state (convention - excluded from public types)
-5. **Never use `$state()`** for props - props are automatically reactive
-6. **Use `$state()`** for internal state (non-props) that needs reactivity
-
----
-
-## Using Origins in Components
-
-### `$origin.component(Factory)` — Standard Component Usage
-
-**This is the ONLY way to use origins inside `.svelte` components when you want props to flow from the parent.**
-
-> ⚠️ **Component-only:** This macro throws an error if used in `.svelte.ts` module files.
-
-```svelte
-<!-- Counter.svelte -->
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-
-	let counter = $origin.component(Counter)
-</script>
-
-<div>
-	<span>{counter.props.label}: {counter.props.count}</span>
-	<button onclick={counter.increment}>+{counter.props.step}</button>
-	<button onclick={counter.decrement}>-{counter.props.step}</button>
-	<small>Doubled: {counter.doubled}</small>
-</div>
-```
-
-**What happens at compile time:**
-
-```svelte
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-
-	type $$Props = $origin.Props<typeof Counter>
-	let { label = 'Counter', count = $bindable(0), step = 1 } = $props()
-	let __attrs = { 
-		get label() { return label }, 
-		get count() { return count }, 
-		set count(v) { count = v },
-		get step() { return step }
-	}
-	let counter = Counter(__attrs)
-</script>
-```
-
-The component's props are **automatically extracted** from the origin's schema. The parent component can pass these props normally:
-
-```svelte
-<Counter label="My Counter" count={5} step={2} />
-```
-
----
-
-## Programmatic Origin Creation
-
-### ⚠️ NEVER Call the Factory Directly
-
-**WRONG** - This DOES NOT maintain reactivity:
-
-```ts
-// ❌ BAD - Never do this!
-const counter = Counter({
-	count: 0,
-	label: 'Test'
-})
-// counter.props.count = 5  ← This WON'T trigger reactivity!
-```
-
-The input object `{ count: 0, label: 'Test' }` is a **plain object**, not a reactive proxy. Setting `counter.props.count` won't trigger Svelte's reactivity system.
-
-### ✅ Use `$origin.create()` Instead
-
-**CORRECT** - Use `$origin.create()` for programmatic creation:
-
-```ts
-// ✅ GOOD - Always use $origin.create()
-const counter = $origin.create(Counter, {
-	count: 0,
-	label: 'Test'
-})
-// counter.props.count ← Readable, but NOT settable (read-only)
-// counter.increment() ← Methods can still modify props internally!
-```
-
-> **Note:** Props passed directly are **read-only** (getter-only). To set props externally, use `$origin.bind()`.
-
-### `$origin.create()` Works Everywhere
-
-Unlike `$origin.component()` which only works in `.svelte` files, `$origin.create()` can be used in:
-
-- ✅ `.svelte` component scripts
-- ✅ `.svelte.ts` / `.svelte.js` module files
-- ✅ Inside `$origin()` init callbacks
-- ✅ Inside origin method bodies
-- ✅ Module scripts (`<script module>`)
-
-**What happens at compile time (regular props → getter-only):**
-
-```ts
-let __attrs = {
-	// Regular props are getter-only (read-only from outside)
-	get count() { return 0 },
-	get label() { return 'Test' }
-}
-const counter = Counter(__attrs)
-```
-
-**What happens with `$origin.bind()` (getter + setter):**
-
-```ts
-let myCount = $state(0)
-let __attrs = {
-	get count() { return myCount },
-	set count(v) { myCount = v }  // Two-way binding!
-}
-const counter = Counter(__attrs)
-```
-
-### `$origin.bind(variable)` — Required for Settable Props
-
-To set an origin's prop externally (or sync with existing state), you **must** use `$origin.bind()`:
-
-```ts
-// In an origin's init or .svelte.ts file
-let sharedItems = $state(['a', 'b', 'c'])
-
-const list = $origin.create(ListOrigin, {
-	items: $origin.bind(sharedItems)  // Two-way binding!
-})
-
-// Both are now in sync:
-sharedItems.push('d')        // list.props.items now includes 'd'
-list.props.items = ['x']     // sharedItems is now ['x']
-```
-
-Mix bound and unbound props:
-
-```ts
-let count = $state(0)
-
-const counter = $origin.create(Counter, {
-	count: $origin.bind(count),  // Settable (two-way)
-	label: 'My Counter',         // Read-only
-	step: 2                      // Read-only
-})
-
-counter.props.count = 10     // ✅ Works - updates `count` too
-counter.props.label = 'New'  // ❌ No effect (read-only)
-```
-
----
-
-## Prop Forwarding
-
-### `$origin.for(Factory)` — Forward Props to Child
-
-> ⚠️ **Component-only:** This macro throws an error if used in `.svelte.ts` module files.
-
-Use in wrapper components that need to pass props through:
-
-```svelte
-<!-- Wrapper.svelte -->
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-	import CounterComponent from './Counter.svelte'
-
-	let counterProps = $origin.for(Counter)
-</script>
-
-<div class="wrapper">
-	<CounterComponent {...counterProps} />
-</div>
-```
-
-### `$origin.for('element')` — Forward Props to HTML Elements
-
-```svelte
-<!-- CustomInput.svelte -->
-<script lang="ts">
-	let inputProps = $origin.for('input')
-</script>
-
-<input {...inputProps} class="custom-input" />
-```
-
----
-
-## Inheritance
-
-Origins can extend other origins using array syntax:
-
-```ts
-// base.svelte.ts
-export const BaseCounter = $origin({
-	props: $origin.props({
-		count: $bindable(0)
-	}),
-
-	increment() {
-		this.props.count++
-	}
-})
-
-// extended.svelte.ts  
-export const ExtendedCounter = $origin([BaseCounter], {
-	props: $origin.props({
-		step: 1  // Additional prop (merged with parent)
-	}),
-
-	// Override with super call
-	increment() {
-		this.super.increment()  // Call parent
-		console.log('Incremented!')
-	},
-
-	// New method
-	incrementByStep() {
-		this.props.count += this.props.step
-	}
-})
-```
-
-### Inheritance Rules
-
-1. Child props are **merged** with parent props (left-to-right, child overrides)
-2. Use `this.super.*` to call parent methods
-3. Child methods override parent methods with same name
-4. Derived values can be overridden
-5. Multi-level inheritance works: `this.super.super.*` for grandparent
-
-### Standalone Props Inheritance
-
-Props can also inherit from other props schemas:
-
-```ts
-export const BaseAttrs = $origin.props({
-	id: '',
-	class: ''
-})
-
-export const WidgetAttrs = $origin.props([BaseAttrs], {
-	label: 'Widget',
-	active: false
-})
-// WidgetAttrs has: id, class, label, active
-```
-
----
-
-## Type Helpers
-
-### `$origin.Props<typeof Factory>`
-
-Extract the component props type from an origin factory:
-
-```svelte
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-
-	// Explicit type annotation (optional but helps IDE)
-	type $$Props = $origin.Props<typeof Counter>
-
-	let counter = $origin.component(Counter)
-</script>
-```
-
-### `$origin.Of<typeof Factory>`
-
-Extract the instance type from an origin factory:
-
-```ts
-import { Counter } from './counter.svelte'
-
-// Type a variable that will hold an origin instance
-let counter: $origin.Of<typeof Counter>
-
-// Useful for optional or lazy initialization
-let maybeCounter: $origin.Of<typeof Counter> | undefined = undefined
-
-// Also works with generic factories
-const List = <T>() => $origin({ props: $origin.props({ items: [] as T[] }) })
-type StringListInstance = $origin.Of<ReturnType<typeof List<string>>>
-```
-
----
-
-## Reactivity Internals
-
-### How Props Become Reactive
-
-Origins use **getter/setter pairs** to maintain reactivity. The key distinction:
-
-| Source | Props become | Settable externally? |
-|--------|--------------|---------------------|
-| `$origin.component()` | Connected to `$props()` | ✅ Bindable props only |
-| `$origin.create({ prop: value })` | Getter-only | ❌ No |
-| `$origin.create({ prop: $origin.bind(var) })` | Getter + setter | ✅ Yes |
-
-**Getter-only props (default for `$origin.create`):**
-
-```ts
-// Input
-$origin.create(Counter, { count: 0 })
-
-// Output - getter-only
-let __attrs = { get count() { return 0 } }
-```
-
-**Getter + setter props (with `$origin.bind`):**
-
-```ts
-// Input
-let count = $state(0)
-$origin.create(Counter, { count: $origin.bind(count) })
-
-// Output - getter AND setter
-let __attrs = {
-	get count() { return count },
-	set count(v) { count = v }
-}
-```
-
-### Why Internal Methods Still Work
-
-Even though external setting doesn't work for regular props, **origin methods** can still modify props internally because they work through `this.props.*` which bypasses the external getter-only constraint:
-
-```ts
-// Origin method can modify props
-increment() {
-	this.props.count++  // ✅ Works - internal modification
-}
-```
-
----
-
-## Common Patterns
-
-### State Machine Origin
-
-```ts
-export const StateMachine = $origin({
-	props: $origin.props({
-		initial: 'idle' as 'idle' | 'loading' | 'success' | 'error'
-	}),
-
-	_currentState: null as string | null,
-
-	get state() {
-		return $derived(this._currentState ?? this.props.initial)
-	},
-
-	transition(to: string) {
-		this._currentState = to
-	},
-
-	get isLoading() {
-		return $derived(this.state === 'loading')
-	}
-})
-```
-
-### Form Field Origin
-
-```ts
-export const FormField = $origin({
-	props: $origin.props({
-		value: $bindable(''),
-		label: '',
-		required: false,
-		validate: ((v: string) => true) as (v: string) => boolean | string
-	}),
-
-	_touched: false,
-
-	get error() {
-		if (!this._touched) return null
-		const result = this.props.validate(this.props.value)
-		return $derived(result === true ? null : result)
-	},
-
-	get isValid() {
-		return $derived(this.error === null)
-	},
-
-	touch() {
-		this._touched = true
-	},
-
-	reset() {
-		this.props.value = ''
-		this._touched = false
-	}
-})
-```
-
-### Composing Origins
-
-```ts
-// Create child origin inside parent using init callback
-export const Parent = $origin({
-	props: $origin.props({
-		items: [] as string[]
-	}),
-
-	// Child origin with bound props
-	_child: null as ReturnType<typeof ChildOrigin> | null
-}, function() {
-	// Init callback - runs when instance is created
-	this._child = $origin.create(ChildOrigin, {
-		items: $origin.bind(this.props.items)  // Sync with parent
-	})
-})
-```
-
----
-
-## Quick Reference
-
-### File Types & Allowed Macros
-
-| Extension | Purpose | Macros Available |
-|-----------|---------|------------------|
-| `.svelte.ts` | Origin definitions | `$origin()`, `$origin.props()`, `$origin.create()`, `$origin.bind()`, `$bindable()` |
-| `.svelte` | Svelte components | `$origin.component()`, `$origin.for()`, `$origin.create()`, `$origin.bind()` |
-
-### Context-Specific Macros
-
-| Macro | `.svelte` | `.svelte.ts` | Init callbacks |
-|-------|:---------:|:------------:|:--------------:|
-| `$origin.component()` | ✅ | ❌ throws | ❌ throws |
-| `$origin.for()` | ✅ | ❌ throws | ❌ throws |
-| `$origin.create()` | ✅ | ✅ | ✅ |
-| `$origin.bind()` | ✅ | ✅ | ✅ |
-| `$origin.props()` | ✅ | ✅ | ✅ |
-
-### Do's and Don'ts
-
-| ✅ DO | ❌ DON'T |
-|-------|----------|
-| Use `$origin.component(Factory)` in `.svelte` components | Use `$origin.component()` in `.svelte.ts` files |
-| Use `$origin.create(Factory, props)` for programmatic creation | Call `Factory({...})` directly (breaks reactivity) |
-| Use `$origin.bind(variable)` for two-way shared state | Pass reactive variables without binding |
-| Use `$derived()` for computed values in getters | Use `$state()` for props (they're already reactive) |
-| Access props via `this.props.*` | Destructure props at top level of definition |
-| Prefix private state with `_` | Expose internal state publicly |
-| Use `$origin.Of<typeof F>` for instance types | Use `ReturnType<typeof F>` (less inference) |
-| Use `$origin.Props<typeof F>` for props types | Manually define props types |
-
-### Common LLM Pitfalls
-
-1. **Calling factory directly** - `Counter({...})` loses reactivity. Always use `$origin.create()` or `$origin.component()`.
-
-2. **Using `$origin.component()` in module files** - This only works in `.svelte` files. In `.svelte.ts`, use `$origin.create()`.
-
-3. **Using `$origin.for()` in module files** - This only works in `.svelte` files.
-
-4. **Forgetting `this.props`** - Inside origins, always use `this.props.count`, not just `count` or `props.count`.
-
-5. **Using `$state()` for props** - Props passed to `$origin.props({...})` are automatically reactive. Don't wrap defaults in `$state()`.
-
-6. **Missing `$derived()` in getters** - Computed values must use `$derived()` inside getters for reactivity.
-
-7. **Expecting settable props without `$origin.bind()`** - Props in `$origin.create({ prop: value })` are **read-only**. To set props externally, use `$origin.bind(variable)`.
+# svelte-origin - LLM Reference
+
+> Quick-reference documentation for LLM assistance with svelte-origin v3.0
+
+## Overview
+
+`svelte-origin` provides a macro-based system for defining reusable state + props + methods patterns in Svelte 5. Origins are factories that create reactive instances with props, state, derived values, and methods.
+
+**IMPORTANT**: This library uses **compile-time macros** (prefixed with `$`). These are transformed during build and do NOT exist at runtime.
+
+---
+
+## The `$origin` Namespace
+
+All macros live under the `$origin` namespace:
+
+| Macro | Context | Description |
+|-------|---------|-------------|
+| `$origin({...})` | `.svelte.ts` files | Define an origin factory |
+| `$origin.props({...})` | Anywhere | Define props schema with defaults |
+| `$origin.component(Factory)` | ⚠️ `.svelte` only | Create origin from component `$props()` |
+| `$origin.create(Factory, {...})` | ✅ Everywhere | Programmatic origin creation with reactivity |
+| `$origin.bind(variable)` | Inside `$origin.create()` | Bind prop to existing reactive variable |
+| `$origin.for(Factory)` | ⚠️ `.svelte` only | Forward props to child origin/element |
+| `$origin.Props<typeof Factory>` | Type context | Extract component props type |
+| `$origin.Of<typeof Factory>` | Type context | Extract origin instance type |
+| `$bindable(value)` | Inside `$origin.props({})` | Mark a prop as two-way bindable |
+
+### Context Restrictions
+
+- ⚠️ **Component-only macros** (`$origin.component()`, `$origin.for()`): Using these in `.svelte.ts` or `.svelte.js` module files will throw a helpful compile-time error
+- ✅ **Universal macros** (`$origin.create()`, `$origin.props()`): Work in any context
+
+---
+
+## Defining Origins (`.svelte.ts` files)
+
+Origins are defined in `.svelte.ts` files using the `$origin()` macro:
+
+```ts
+// counter.svelte.ts
+export const Counter = $origin({
+	props: $origin.props({
+		label: 'Counter',           // Default string
+		count: $bindable(0),        // Bindable number (two-way)
+		step: 1                     // Default number
+	}),
+
+	// Internal state (not exposed - prefix with _)
+	_history: [] as number[],
+
+	// Derived values (use getters + $derived)
+	get doubled() {
+		return $derived(this.props.count * 2)
+	},
+
+	// Methods
+	increment() {
+		this._history.push(this.props.count)
+		this.props.count += this.props.step
+	},
+
+	decrement() {
+		this._history.push(this.props.count)
+		this.props.count -= this.props.step
+	}
+})
+```
+
+### Key Rules for Origin Definitions
+
+1. **Use `this.props.*`** to access props (not `props.*`)
+2. **Use `$derived()`** for computed/derived values (must be inside a getter)
+3. **Use `$bindable(defaultValue)`** for two-way bindable props
+4. **Prefix with `_`** for internal/private state (convention - excluded from public types)
+5. **Never use `$state()`** for props - props are automatically reactive
+6. **Use `$state()`** for internal state (non-props) that needs reactivity
+
+---
+
+## Using Origins in Components
+
+### `$origin.component(Factory)` — Standard Component Usage
+
+**This is the ONLY way to use origins inside `.svelte` components when you want props to flow from the parent.**
+
+> ⚠️ **Component-only:** This macro throws an error if used in `.svelte.ts` module files.
+
+```svelte
+<!-- Counter.svelte -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+
+	let counter = $origin.component(Counter)
+</script>
+
+<div>
+	<span>{counter.props.label}: {counter.props.count}</span>
+	<button onclick={counter.increment}>+{counter.props.step}</button>
+	<button onclick={counter.decrement}>-{counter.props.step}</button>
+	<small>Doubled: {counter.doubled}</small>
+</div>
+```
+
+**What happens at compile time:**
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+
+	type $$Props = $origin.Props<typeof Counter>
+	let { label = 'Counter', count = $bindable(0), step = 1 } = $props()
+	let __attrs = { 
+		get label() { return label }, 
+		get count() { return count }, 
+		set count(v) { count = v },
+		get step() { return step }
+	}
+	let counter = Counter(__attrs)
+</script>
+```
+
+The component's props are **automatically extracted** from the origin's schema. The parent component can pass these props normally:
+
+```svelte
+<Counter label="My Counter" count={5} step={2} />
+```
+
+---
+
+## Programmatic Origin Creation
+
+### ⚠️ NEVER Call the Factory Directly
+
+**WRONG** - This DOES NOT maintain reactivity:
+
+```ts
+// ❌ BAD - Never do this!
+const counter = Counter({
+	count: 0,
+	label: 'Test'
+})
+// counter.props.count = 5  ← This WON'T trigger reactivity!
+```
+
+The input object `{ count: 0, label: 'Test' }` is a **plain object**, not a reactive proxy. Setting `counter.props.count` won't trigger Svelte's reactivity system.
+
+### ✅ Use `$origin.create()` Instead
+
+**CORRECT** - Use `$origin.create()` for programmatic creation:
+
+```ts
+// ✅ GOOD - Always use $origin.create()
+const counter = $origin.create(Counter, {
+	count: 0,
+	label: 'Test'
+})
+// counter.props.count ← Readable, but NOT settable (read-only)
+// counter.increment() ← Methods can still modify props internally!
+```
+
+> **Note:** Props passed directly are **read-only** (getter-only). To set props externally, use `$origin.bind()`.
+
+### `$origin.create()` Works Everywhere
+
+Unlike `$origin.component()` which only works in `.svelte` files, `$origin.create()` can be used in:
+
+- ✅ `.svelte` component scripts
+- ✅ `.svelte.ts` / `.svelte.js` module files
+- ✅ Inside `$origin()` init callbacks
+- ✅ Inside origin method bodies
+- ✅ Module scripts (`<script module>`)
+
+**What happens at compile time (regular props → getter-only):**
+
+```ts
+let __attrs = {
+	// Regular props are getter-only (read-only from outside)
+	get count() { return 0 },
+	get label() { return 'Test' }
+}
+const counter = Counter(__attrs)
+```
+
+**What happens with `$origin.bind()` (getter + setter):**
+
+```ts
+let myCount = $state(0)
+let __attrs = {
+	get count() { return myCount },
+	set count(v) { myCount = v }  // Two-way binding!
+}
+const counter = Counter(__attrs)
+```
+
+### `$origin.bind(variable)` — Required for Settable Props
+
+To set an origin's prop externally (or sync with existing state), you **must** use `$origin.bind()`:
+
+```ts
+// In an origin's init or .svelte.ts file
+let sharedItems = $state(['a', 'b', 'c'])
+
+const list = $origin.create(ListOrigin, {
+	items: $origin.bind(sharedItems)  // Two-way binding!
+})
+
+// Both are now in sync:
+sharedItems.push('d')        // list.props.items now includes 'd'
+list.props.items = ['x']     // sharedItems is now ['x']
+```
+
+Mix bound and unbound props:
+
+```ts
+let count = $state(0)
+
+const counter = $origin.create(Counter, {
+	count: $origin.bind(count),  // Settable (two-way)
+	label: 'My Counter',         // Read-only
+	step: 2                      // Read-only
+})
+
+counter.props.count = 10     // ✅ Works - updates `count` too
+counter.props.label = 'New'  // ❌ No effect (read-only)
+```
+
+---
+
+## Prop Forwarding
+
+### `$origin.for(Factory)` — Forward Props to Child
+
+> ⚠️ **Component-only:** This macro throws an error if used in `.svelte.ts` module files.
+
+Use in wrapper components that need to pass props through:
+
+```svelte
+<!-- Wrapper.svelte -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	import CounterComponent from './Counter.svelte'
+
+	let counterProps = $origin.for(Counter)
+</script>
+
+<div class="wrapper">
+	<CounterComponent {...counterProps} />
+</div>
+```
+
+### `$origin.for('element')` — Forward Props to HTML Elements
+
+```svelte
+<!-- CustomInput.svelte -->
+<script lang="ts">
+	let inputProps = $origin.for('input')
+</script>
+
+<input {...inputProps} class="custom-input" />
+```
+
+---
+
+## Inheritance
+
+Origins can extend other origins using array syntax:
+
+```ts
+// base.svelte.ts
+export const BaseCounter = $origin({
+	props: $origin.props({
+		count: $bindable(0)
+	}),
+
+	increment() {
+		this.props.count++
+	}
+})
+
+// extended.svelte.ts  
+export const ExtendedCounter = $origin([BaseCounter], {
+	props: $origin.props({
+		step: 1  // Additional prop (merged with parent)
+	}),
+
+	// Override with super call
+	increment() {
+		this.super.increment()  // Call parent
+		console.log('Incremented!')
+	},
+
+	// New method
+	incrementByStep() {
+		this.props.count += this.props.step
+	}
+})
+```
+
+### Inheritance Rules
+
+1. Child props are **merged** with parent props (left-to-right, child overrides)
+2. Use `this.super.*` to call parent methods
+3. Child methods override parent methods with same name
+4. Derived values can be overridden
+5. Multi-level inheritance works: `this.super.super.*` for grandparent
+
+### Standalone Props Inheritance
+
+Props can also inherit from other props schemas:
+
+```ts
+export const BaseAttrs = $origin.props({
+	id: '',
+	class: ''
+})
+
+export const WidgetAttrs = $origin.props([BaseAttrs], {
+	label: 'Widget',
+	active: false
+})
+// WidgetAttrs has: id, class, label, active
+```
+
+---
+
+## Type Helpers
+
+### `$origin.Props<typeof Factory>`
+
+Extract the component props type from an origin factory. Useful for typing in non-component contexts:
+
+```ts
+import { Counter } from './counter.svelte'
+
+// Use in utility functions or type definitions
+function processProps(props: $origin.Props<typeof Counter>) {
+	console.log(props.count)
+}
+```
+
+> ⚠️ **Anti-pattern:** Do NOT manually declare `type $$Props = ...` in `.svelte` components. 
+> `svelte-origin` automatically generates the correct `$$Props` type from the origin schema.
+> Manually declaring it can cause type mismatches and breaks the automatic prop extraction.
+
+### `$origin.Of<typeof Factory>`
+
+Extract the instance type from an origin factory:
+
+```ts
+import { Counter } from './counter.svelte'
+
+// Type a variable that will hold an origin instance
+let counter: $origin.Of<typeof Counter>
+
+// Useful for optional or lazy initialization
+let maybeCounter: $origin.Of<typeof Counter> | undefined = undefined
+
+// Also works with generic factories
+const List = <T>() => $origin({ props: $origin.props({ items: [] as T[] }) })
+type StringListInstance = $origin.Of<ReturnType<typeof List<string>>>
+```
+
+---
+
+## Reactivity Internals
+
+### How Props Become Reactive
+
+Origins use **getter/setter pairs** to maintain reactivity. The key distinction:
+
+| Source | Props become | Settable externally? |
+|--------|--------------|---------------------|
+| `$origin.component()` | Connected to `$props()` | ✅ Bindable props only |
+| `$origin.create({ prop: value })` | Getter-only | ❌ No |
+| `$origin.create({ prop: $origin.bind(var) })` | Getter + setter | ✅ Yes |
+
+**Getter-only props (default for `$origin.create`):**
+
+```ts
+// Input
+$origin.create(Counter, { count: 0 })
+
+// Output - getter-only
+let __attrs = { get count() { return 0 } }
+```
+
+**Getter + setter props (with `$origin.bind`):**
+
+```ts
+// Input
+let count = $state(0)
+$origin.create(Counter, { count: $origin.bind(count) })
+
+// Output - getter AND setter
+let __attrs = {
+	get count() { return count },
+	set count(v) { count = v }
+}
+```
+
+### Why Internal Methods Still Work
+
+Even though external setting doesn't work for regular props, **origin methods** can still modify props internally because they work through `this.props.*` which bypasses the external getter-only constraint:
+
+```ts
+// Origin method can modify props
+increment() {
+	this.props.count++  // ✅ Works - internal modification
+}
+```
+
+---
+
+## Common Patterns
+
+### State Machine Origin
+
+```ts
+export const StateMachine = $origin({
+	props: $origin.props({
+		initial: 'idle' as 'idle' | 'loading' | 'success' | 'error'
+	}),
+
+	_currentState: null as string | null,
+
+	get state() {
+		return $derived(this._currentState ?? this.props.initial)
+	},
+
+	transition(to: string) {
+		this._currentState = to
+	},
+
+	get isLoading() {
+		return $derived(this.state === 'loading')
+	}
+})
+```
+
+### Form Field Origin
+
+```ts
+export const FormField = $origin({
+	props: $origin.props({
+		value: $bindable(''),
+		label: '',
+		required: false,
+		validate: ((v: string) => true) as (v: string) => boolean | string
+	}),
+
+	_touched: false,
+
+	get error() {
+		if (!this._touched) return null
+		const result = this.props.validate(this.props.value)
+		return $derived(result === true ? null : result)
+	},
+
+	get isValid() {
+		return $derived(this.error === null)
+	},
+
+	touch() {
+		this._touched = true
+	},
+
+	reset() {
+		this.props.value = ''
+		this._touched = false
+	}
+})
+```
+
+### Composing Origins
+
+```ts
+// Create child origin inside parent using init callback
+export const Parent = $origin({
+	props: $origin.props({
+		items: [] as string[]
+	}),
+
+	// Child origin with bound props
+	_child: null as ReturnType<typeof ChildOrigin> | null
+}, function() {
+	// Init callback - runs when instance is created
+	this._child = $origin.create(ChildOrigin, {
+		items: $origin.bind(this.props.items)  // Sync with parent
+	})
+})
+```
+
+---
+
+## Quick Reference
+
+### File Types & Allowed Macros
+
+| Extension | Purpose | Macros Available |
+|-----------|---------|------------------|
+| `.svelte.ts` | Origin definitions | `$origin()`, `$origin.props()`, `$origin.create()`, `$origin.bind()`, `$bindable()` |
+| `.svelte` | Svelte components | `$origin.component()`, `$origin.for()`, `$origin.create()`, `$origin.bind()` |
+
+### Context-Specific Macros
+
+| Macro | `.svelte` | `.svelte.ts` | Init callbacks |
+|-------|:---------:|:------------:|:--------------:|
+| `$origin.component()` | ✅ | ❌ throws | ❌ throws |
+| `$origin.for()` | ✅ | ❌ throws | ❌ throws |
+| `$origin.create()` | ✅ | ✅ | ✅ |
+| `$origin.bind()` | ✅ | ✅ | ✅ |
+| `$origin.props()` | ✅ | ✅ | ✅ |
+
+### Do's and Don'ts
+
+| ✅ DO | ❌ DON'T |
+|-------|----------|
+| Use `$origin.component(Factory)` in `.svelte` components | Use `$origin.component()` in `.svelte.ts` files |
+| Use `$origin.create(Factory, props)` for programmatic creation | Call `Factory({...})` directly (breaks reactivity) |
+| Use `$origin.bind(variable)` for two-way shared state | Pass reactive variables without binding |
+| Use `$derived()` for computed values in getters | Use `$state()` for props (they're already reactive) |
+| Access props via `this.props.*` | Destructure props at top level of definition |
+| Prefix private state with `_` | Expose internal state publicly |
+| Let svelte-origin auto-generate `$$Props` | Manually declare `type $$Props = ...` |
+| Use `$origin.Of<typeof F>` for instance types | Use `ReturnType<typeof F>` (less inference) |
+| Use `$origin.Props<typeof F>` for type utilities | Use `$$Props` directly in component code |
+
+### Common LLM Pitfalls
+
+1. **Calling factory directly** - `Counter({...})` loses reactivity. Always use `$origin.create()` or `$origin.component()`.
+
+2. **Using `$origin.component()` in module files** - This only works in `.svelte` files. In `.svelte.ts`, use `$origin.create()`.
+
+3. **Using `$origin.for()` in module files** - This only works in `.svelte` files.
+
+4. **Forgetting `this.props`** - Inside origins, always use `this.props.count`, not just `count` or `props.count`.
+
+5. **Using `$state()` for props** - Props passed to `$origin.props({...})` are automatically reactive. Don't wrap defaults in `$state()`.
+
+6. **Missing `$derived()` in getters** - Computed values must use `$derived()` inside getters for reactivity.
+
+7. **Expecting settable props without `$origin.bind()`** - Props in `$origin.create({ prop: value })` are **read-only**. To set props externally, use `$origin.bind(variable)`.
+
+8. **Manually declaring `$$Props`** - Never write `type $$Props = ...` in components using `$origin.component()`. The transformer auto-generates this from the origin schema. Manual declarations cause type conflicts and may break prop extraction. Ensure `svelte.config.js` includes the svelte-origin preprocessor for proper type generation.