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

package/README.md

@@ -1,678 +1,678 @@
-# svelte-origin
-
-Compiler-assisted state and prop ergonomics for **Svelte 5**.
-
-`svelte-origin` is intentionally **tooling-first**:
-
-- you write small, declarative “origins” using Svelte 5 runes (`$state`, `$derived`, ...)
-- you create instances explicitly **from props** (`$origin.component(...)`) or **programmatically** (`$origin.create(...)`)
-- you forward props ergonomically (`$origin.for(...)`)
-
-Everything "macro-like" compiles down to plain Svelte 5 code.
-
-## Quick Overview
-
-| Macro | Purpose | Context |
-|-------|---------|--------|
-| `$origin({...})` | Define origin factory | `.svelte.ts` |
-| `$origin.props({...})` | Define props schema | Anywhere |
-| `$origin.component(F)` | Create from `$props()` | `.svelte` only |
-| `$origin.create(F, {...})` | Programmatic creation | ✅ Everywhere |
-| `$origin.bind(var)` | Two-way binding | In `$origin.create()` |
-| `$origin.for(F)` | Forward props | `.svelte` only |
-| `$origin.Props<T>` | Extract props type | Type context |
-| `$origin.Of<T>` | Extract instance type | Type context |
-
-
-## Why this exists
-
-Svelte 5 already has great primitives.
-
-The pain is when you want:
-
-- a *single* place to describe a prop surface (including defaults + bindables)
-- predictable, explicit “create state from props” code
-- clean prop forwarding without manually spelling every prop
-- editor inference that matches what the build does
-
-`svelte-origin` solves this with a **Svelte preprocessor** (and optionally a Vite plugin).
-
-## Installation
-
-```bash
-npm install svelte-origin
-# or
-bun add svelte-origin
-```
-
-## Setup
-
-### 1. Add the Vite plugin
-
-The plugin works with **Vite**, **Rollup**, and **Rolldown**. It transforms macros in both origin files (`.svelte.ts`) and Svelte components.
-
-```ts
-// vite.config.ts
-import { sveltekit } from '@sveltejs/kit/vite'
-import { svelteOrigin } from 'svelte-origin/plugin'
-
-export default {
-	plugins: [
-		svelteOrigin(),  // Must come BEFORE sveltekit/svelte
-		sveltekit()
-	]
-}
-```
-
-For **Rollup**:
-
-```js
-// rollup.config.js
-import svelte from 'rollup-plugin-svelte'
-import { svelteOrigin } from 'svelte-origin/plugin'
-
-export default {
-	plugins: [
-		svelteOrigin(),  // Must come BEFORE svelte
-		svelte()
-	]
-}
-```
-
-### 2. Add the Svelte preprocessor (optional)
-
-The Vite/Rollup plugin handles all transformation. The preprocessor is **optional** — it only suppresses editor warnings about macro identifiers (since `$` is reserved for Svelte runes). If your editor shows warnings like "Unknown rune", add the preprocessor:
-
-```js
-// svelte.config.js
-import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
-import { svelteOriginPreprocess } from 'svelte-origin/preprocess'
-
-export default {
-	preprocess: [
-		svelteOriginPreprocess(),  // Must come BEFORE vitePreprocess
-		vitePreprocess()
-	]
-}
-```
-
-> **Note:** The Vite/Rollup plugin is **required** for transformation — the preprocessor alone is not sufficient.
-
-### 3. Add TypeScript globals
-
-Add `svelte-origin/globals` to your `tsconfig.json` to enable types for `$origin`, `$origin.component`, etc.
-
-```json
-{
-	"compilerOptions": {
-		"types": [
-			"svelte-origin/globals"
-		]
-	}
-}
-```
-
-### Plugin options
-
-```ts
-svelteOrigin({
-	// File extensions for origin definitions
-	extensions: ['.svelte.ts', '.svelte.js', '.origin.svelte.ts'],
-	
-	// Enable debug logging
-	debug: false,
-	
-	// Output transformed code to .transformed.txt files for debugging
-	outputTransformed: false,
-	
-	// Directory for transformed output files (defaults to same as source)
-	// The directory will be created automatically if it doesn't exist.
-	// This setting is shared with the preprocessor, so both .svelte.ts and
-	// .svelte files will output to the same directory.
-	outputDir: undefined
-})
-```
-
-## The core idea
-
-### 1) Define an origin
-
-Write origins in a file where runes are allowed (e.g. `.svelte.ts`).
-
-```ts
-// counter.svelte.ts
-export const Counter = $origin({
-	props: $origin.props({
-		/** The label for the counter */
-		label: 'Counter',
-		/** The current count value (bindable for two-way binding) */
-		count: $bindable(0),
-		/** Step value for increment/decrement (optional) */
-		step: 1 as number
-	}),
-
-	/** Internal counter (private - not exposed) */
-	_incrementCount: $state(0),
-
-	/** Get double the current count */
-	get double() {
-		return $derived(this.props.count * 2)
-	},
-
-	/** Increment by step */
-	increment() {
-		this._incrementCount++
-		this.props.count += this.props.step
-	},
-
-	/** Decrement by step */
-	decrement() {
-		this.props.count -= this.props.step
-	},
-
-	/** Reset to zero */
-	reset() {
-		this.props.count = 0
-	}
-})
-```
-
-Notes:
-
-- `$origin(...)` is a **compile-time macro** provided by `svelte-origin` (not a Svelte rune)
-- `props: $origin.props({...})` defines the component props schema
-	- compiles into the origin's prop schema with defaults and bindable handling
-	- the property name (`props`) is the recommended convention
-- `$bindable(...)` inside `props: $origin.props({...})` marks props for two-way binding
-- `$state`/`$derived` are real Svelte runes
-- Properties prefixed with `_` (like `_incrementCount`) are private and not exposed on the instance type
-
-### 2) Create an instance from component props
-
-Inside a component, be explicit that the instance is derived from the component's props:
-
-```svelte
-<!-- CounterComponent.svelte -->
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-	
-	// Create the counter instance from component props
-	let counter = $origin.component(Counter)
-</script>
-
-<div class="counter">
-	<h3>{counter.props.label}</h3>
-	<p>{counter.props.count}</p>
-	<p>Double: {counter.double}</p>
-	<div class="controls">
-		<button onclick={() => counter.decrement()}>-{counter.props.step}</button>
-		<button onclick={() => counter.reset()}>Reset</button>
-		<button onclick={() => counter.increment()}>+{counter.props.step}</button>
-	</div>
-</div>
-```
-
-Key points:
-
-- We do **not** rely on "calling `Counter()` magically reads `$props()`"
-- We make the props dependency explicit via `$origin.component(Counter)`
-- For manual type declarations, use `$origin.Props<typeof Counter>`
-
-Under the hood, the macro expands to canonical `$props()` usage, so the component's prop types remain inferable.
-
-## Passing to subcomponents
-
-The rule of thumb is:
-
-- each component owns its own origin instance
-- parents forward values via props
-
-We make forwarding ergonomic using `$origin.for(...)`. This helper forwards the intersection of the parent's props and the child's origin requirements.
-
-> ⚠️ **Note:** `$origin.for()` only works in `.svelte` files. It throws an error if used in `.svelte.ts` module files.
-
-```svelte
-<script lang='ts'>
-	let childProps = $origin.for(ChildOrigin)
-</script>
-
-<Child {...childProps} />
-```
-
-Notes:
-
-- `$origin.for(...)` is intentionally about forwarding **from `$props()`**, not from an origin instance
-
-## Wrapper components / element props
-
-If you’re forwarding attributes onto a native element, the type you want is an **attribute type**, not `HTMLInputElement`.
-
-Svelte’s recommended types live in `svelte/elements`.
-
-To make this ergonomic, we can provide:
-
-```svelte
-<script lang='ts'>
-	let inputProps = $origin.for('input')
-</script>
-
-<input {...inputProps} />
-```
-
-(`$origin.for` is a macro that expands to a typed `$props()` + rest pattern.)
-
-
-
-## Extending origins
-
-You can extend existing origins by passing them as an array in the first argument. To access the parent implementation, use `this.super`.
-
-```ts
-export const Counter = $origin({
-	// ... base implementation
-	increment() {
-		this.props.count += 1
-	}
-})
-
-export const SuperCounter = $origin([Counter], {
-	increment() {
-		// Call the parent implementation
-		this.super.increment()
-		console.log('Incremented!')
-	}
-})
-```
-
-## Programmatic Origin Creation
-
-Use `$origin.create()` to create origin instances **programmatically**. Unlike `$origin.component()`, this works **everywhere**:
-
-- ✅ `.svelte` component scripts
-- ✅ `.svelte.ts` / `.svelte.js` module files  
-- ✅ Inside `$origin()` init callbacks
-- ✅ Inside origin method bodies
-- ✅ Module scripts (`<script module>`)
-
-### Basic Usage
-
-```ts
-import { Counter } from './counter.svelte'
-
-// Create an origin instance with initial prop values
-const counter = $origin.create(Counter, { count: 10, step: 2 })
-
-// Reading props works
-counter.props.count       // ✅ Returns 10
-counter.increment()       // ✅ Methods work
-
-// Without props (uses defaults)
-const defaultCounter = $origin.create(Counter)
-```
-
-> **Note:** Props passed directly to `$origin.create()` are **read-only** (getter-only). If you need to set props externally, use `$origin.bind()` to create two-way bindings.
-
-### Binding to Existing State (Two-Way Reactivity)
-
-Use `$origin.bind()` to sync an origin's prop with an existing reactive variable. **This is the only way to get settable props** with `$origin.create()`:
-
-```ts
-let count = $state(10)
-
-const counter = $origin.create(Counter, {
-	count: $origin.bind(count)  // Two-way binding
-})
-
-// Both are now in sync:
-counter.props.count = 20    // ✅ count is now 20
-count = 5                   // counter.props.count is now 5
-counter.increment()         // ✅ Both update
-```
-
-Mix bound and unbound props as needed:
-
-```ts
-let sharedCount = $state(0)
-
-const counter = $origin.create(Counter, {
-	count: $origin.bind(sharedCount),  // Two-way (settable)
-	label: 'My Counter',               // Read-only
-	step: 2                            // Read-only
-})
-```
-
-### Why Not Call the Factory Directly?
-
-**Never call the factory directly** — it bypasses the transform and breaks reactivity:
-
-```ts
-// ❌ BAD - Bypasses macro transformation
-const counter = Counter({ count: 0 })
-// Props are plain object - no reactivity at all!
-
-// ✅ GOOD - Use $origin.create() for proper transformation
-const counter = $origin.create(Counter, { count: 0 })
-// Props are getter-based and can read from reactive sources
-```
-
-**To set props externally**, you must bind to a reactive variable:
-
-```ts
-let count = $state(0)
-
-const counter = $origin.create(Counter, { 
-	count: $origin.bind(count)  // Now settable!
-})
-
-counter.props.count = 5  // ✅ Works - updates `count` too
-```
-
-## Attachments
-
-Origins can define **attachment methods** that run when an element is attached to the DOM. These are methods prefixed with `$` that receive the element and optionally return a cleanup function.
-
-### Defining attachments
-
-```ts
-// widget.svelte.ts
-export const Widget = $origin({
-	props: $origin.props({
-		color: 'blue'
-	}),
-
-	/** Attachment: adds a tooltip to an element */
-	$tooltip(element: Element) {
-		const tooltip = document.createElement('div')
-		tooltip.textContent = 'Tooltip for ' + this.props.color
-		element.appendChild(tooltip)
-		
-		// Return cleanup function
-		return () => tooltip.remove()
-	},
-
-	/** Attachment: highlights the element */
-	$highlight(element: Element) {
-		element.classList.add('highlighted')
-		return () => element.classList.remove('highlighted')
-	}
-})
-```
-
-### Using attachments
-
-Spread `$attachments` onto any element to apply all defined attachment behaviors:
-
-```svelte
-<script lang="ts">
-	import { Widget } from './widget.svelte'
-	let widget = $origin.component(Widget)
-</script>
-
-<!-- All attachment methods are applied to this div -->
-<div {...widget.$attachments}>
-	Content with tooltip and highlight
-</div>
-```
-
-### Forwarding incoming attachments
-
-When a parent uses Svelte's `{@attach ...}` directive on your component, those attachments are automatically included in `$attachments`:
-
-```svelte
-<!-- Parent.svelte -->
-<WidgetComponent {@attach myCustomAttachment} />
-```
-
-```svelte
-<!-- WidgetComponent.svelte -->
-<script lang="ts">
-	import { Widget } from './widget.svelte'
-	let widget = $origin.component(Widget)
-</script>
-
-<!-- Both origin-defined AND incoming attachments are applied -->
-<div {...widget.$attachments}>...</div>
-```
-
-This enables composable attachment behavior where parents can add behaviors to child component elements.
-
-## Init Callbacks
-
-Origins support an optional init callback that runs when the origin instance is created:
-
-```ts
-export const Timer = $origin({
-	props: $origin.props({
-		interval: 1000
-	}),
-	
-	_count: $state(0),
-	
-	get count() {
-		return $derived(this._count)
-	}
-}, function() {
-	// Runs when the component is created
-	const id = setInterval(() => {
-		this._count++
-	}, this.props.interval)
-	
-	// Return cleanup function (runs on unmount)
-	return () => clearInterval(id)
-})
-```
-
-The callback:
-- Runs after the instance is created
-- Has access to `this` (the full instance including private members)
-- Can return a cleanup function that runs when the component is destroyed
-
-### Origins Without Props (State-Only Origins)
-
-Origins don't require props — you can define pure internal state:
-
-```ts
-// simple.svelte.ts
-export const SimpleCounter = $origin({
-	count: $state(0),
-	increment() { this.count++ },
-	decrement() { this.count-- },
-	reset() { this.count = 0 }
-})
-```
-
-### Creating Child Origins
-
-When an origin needs to create other origin instances, **always use `$origin.create()`**:
-
-```ts
-// Manager that creates child origins
-export const Manager = $origin({
-	name: $state('Manager'),
-	
-	// Pattern 1: Inline initialization
-	childCounter: $origin.create(SimpleCounter),
-	
-	// Pattern 2: Lazy initialization (typed with $origin.Of)
-	lazyChild: $state(undefined) as undefined | $origin.Of<typeof SimpleCounter>
-}, function() {
-	// Pattern 3: Init callback initialization - ALSO use $origin.create()
-	this.lazyChild = $origin.create(SimpleCounter)
-})
-```
-
-> **Critical:** Never call the factory directly (e.g., `SimpleCounter({})`). This loses reactivity. Always use `$origin.create()` — it gets transformed at compile time.
-
-### Type Utilities
-
-```ts
-import { Counter } from './counter.svelte'
-
-// Extract props type (for component prop declarations)
-type CounterProps = $origin.Props<typeof Counter>
-
-// Extract instance type (for variable declarations)
-type CounterInstance = $origin.Of<typeof Counter>
-let counter: $origin.Of<typeof Counter>
-```
-
-```svelte
-<script lang="ts">
-	import { SimpleCounter, Manager } from './simple.svelte'
-
-	// Create instances using $origin.create() for proper reactivity
-	const counter = $origin.create(SimpleCounter)
-	const manager = $origin.create(Manager)
-</script>
-
-<!-- SimpleCounter (no props) -->
-<p>count = {counter.count}</p>
-<button onclick={() => counter.increment()}>Increment</button>
-
-<!-- Manager (with child created in init) -->
-<p>manager.name = {manager.name}</p>
-{#if manager.childCounter}
-	<p>childCounter.count = {manager.childCounter.count}</p>
-	<button onclick={() => manager.childCounter?.increment()}>Increment Child</button>
-{/if}
-```
-
-### `$origin.component()` vs `$origin.create()`
-
-| | `$origin.component()` | `$origin.create()` |
-|---|---|---|
-| **Use in** | `.svelte` files only | ✅ Everywhere |
-| **Props source** | Component's `$props()` | Passed explicitly or omitted |
-| **Prop mutability** | Bindable props are settable | Read-only unless using `$origin.bind()` |
-| **Two-way binding** | Tied to parent via `$bindable()` props | Use `$origin.bind(variable)` |
-| **Typical use** | Component state management | Child origins, tests, modules |
-| **Module file behavior** | ❌ Throws error | ✅ Works |
-
-```svelte
-<!-- Component: uses $origin.component() -->
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-	
-	// Props flow from parent component → origin instance
-	let counter = $origin.component(Counter)
-</script>
-```
-
-```ts
-// Origin file: uses $origin.create()
-import { SimpleCounter } from './simple.svelte'
-
-export const Manager = $origin({
-	// Child is an independent reactive instance
-	child: $origin.create(SimpleCounter)
-})
-```
-
-## Origin Destructuring
-
-Destructure methods and props from origin instances with automatic handling:
-
-### Method Destructuring
-
-Methods are automatically bound to preserve `this` context:
-
-```svelte
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-	let counter = $origin.component(Counter)
-	
-	// Destructure methods - automatically bound
-	let { increment, decrement } = counter
-</script>
-
-<button onclick={increment}>+</button>
-<button onclick={decrement}>-</button>
-```
-
-### Props Destructuring
-
-Props are automatically wrapped in `$derived` for reactivity:
-
-```svelte
-<script lang="ts">
-	import { Counter } from './counter.svelte'
-	let counter = $origin.component(Counter)
-	
-	// Destructure props - automatically reactive
-	let { count, label } = counter.props
-</script>
-
-<p>{label}: {count}</p>
-```
-
-### Nested Destructuring
-
-Combine method and props destructuring:
-
-```svelte
-<script lang="ts">
-	let { increment, props: { count, label } } = counter
-</script>
-```
-
-### Aliases and Defaults
-
-```svelte
-<script lang="ts">
-	let { increment: inc } = counter
-	let { count: counterValue = 0 } = counter.props
-</script>
-```
-
-## CLI (Library Authors)
-
-For library authors, the CLI transforms macros in `svelte-package` output and **eliminates the svelte-origin runtime dependency**.
-
-### Zero-Dependency Output (Default)
-
-By default, the CLI inlines the minimal runtime (~4KB minified) into your library's dist folder:
-
-```bash
-svelte-package && svelte-origin
-```
-
-This means **your library consumers only need Svelte** - no svelte-origin dependency required. The CLI:
-
-1. Transforms any remaining macros in the dist output
-2. Replaces `svelte-origin/runtime` imports with a local inline runtime
-3. Writes `__svelte-origin-runtime.js` to your dist folder
-
-### Keeping svelte-origin as Dependency
-
-If you want consumers to use the full svelte-origin package (e.g., for advanced features or smaller bundle size when multiple libraries use svelte-origin), use `--dependency`:
-
-```bash
-svelte-package && svelte-origin --dependency
-```
-
-### CLI Options
-
-```bash
-svelte-origin [command] [options]
-
-Commands:
-  post-process  Post-process svelte-package output (default)
-  generate-dts  Generate .svelte.d.ts files for svelte-check
-  help          Show help for a command
-
-Post-process options:
-  -h, --help       Show help
-  -n, --dry-run    Show what would be transformed without writing
-  -v, --verbose    Show detailed transformation info
-  -d, --dependency Keep svelte-origin as a runtime dependency (skip inlining)
-
-Examples:
-  svelte-package && svelte-origin                    # Default: inline runtime
-  svelte-package && svelte-origin dist               # Specify directory
-  svelte-package && svelte-origin --dependency       # Keep dependency
-  svelte-origin help post-process                    # Show post-process help
-```
-
-## License
-
-MIT
+# svelte-origin
+
+Compiler-assisted state and prop ergonomics for **Svelte 5**.
+
+`svelte-origin` is intentionally **tooling-first**:
+
+- you write small, declarative “origins” using Svelte 5 runes (`$state`, `$derived`, ...)
+- you create instances explicitly **from props** (`$origin.component(...)`) or **programmatically** (`$origin.create(...)`)
+- you forward props ergonomically (`$origin.for(...)`)
+
+Everything "macro-like" compiles down to plain Svelte 5 code.
+
+## Quick Overview
+
+| Macro | Purpose | Context |
+|-------|---------|--------|
+| `$origin({...})` | Define origin factory | `.svelte.ts` |
+| `$origin.props({...})` | Define props schema | Anywhere |
+| `$origin.component(F)` | Create from `$props()` | `.svelte` only |
+| `$origin.create(F, {...})` | Programmatic creation | ✅ Everywhere |
+| `$origin.bind(var)` | Two-way binding | In `$origin.create()` |
+| `$origin.for(F)` | Forward props | `.svelte` only |
+| `$origin.Props<T>` | Extract props type | Type context |
+| `$origin.Of<T>` | Extract instance type | Type context |
+
+
+## Why this exists
+
+Svelte 5 already has great primitives.
+
+The pain is when you want:
+
+- a *single* place to describe a prop surface (including defaults + bindables)
+- predictable, explicit “create state from props” code
+- clean prop forwarding without manually spelling every prop
+- editor inference that matches what the build does
+
+`svelte-origin` solves this with a **Svelte preprocessor** (and optionally a Vite plugin).
+
+## Installation
+
+```bash
+npm install svelte-origin
+# or
+bun add svelte-origin
+```
+
+## Setup
+
+### 1. Add the Vite plugin
+
+The plugin works with **Vite**, **Rollup**, and **Rolldown**. It transforms macros in both origin files (`.svelte.ts`) and Svelte components.
+
+```ts
+// vite.config.ts
+import { sveltekit } from '@sveltejs/kit/vite'
+import { svelteOrigin } from 'svelte-origin/plugin'
+
+export default {
+	plugins: [
+		svelteOrigin(),  // Must come BEFORE sveltekit/svelte
+		sveltekit()
+	]
+}
+```
+
+For **Rollup**:
+
+```js
+// rollup.config.js
+import svelte from 'rollup-plugin-svelte'
+import { svelteOrigin } from 'svelte-origin/plugin'
+
+export default {
+	plugins: [
+		svelteOrigin(),  // Must come BEFORE svelte
+		svelte()
+	]
+}
+```
+
+### 2. Add the Svelte preprocessor (optional)
+
+The Vite/Rollup plugin handles all transformation. The preprocessor is **optional** — it only suppresses editor warnings about macro identifiers (since `$` is reserved for Svelte runes). If your editor shows warnings like "Unknown rune", add the preprocessor:
+
+```js
+// svelte.config.js
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
+import { svelteOriginPreprocess } from 'svelte-origin/preprocess'
+
+export default {
+	preprocess: [
+		svelteOriginPreprocess(),  // Must come BEFORE vitePreprocess
+		vitePreprocess()
+	]
+}
+```
+
+> **Note:** The Vite/Rollup plugin is **required** for transformation — the preprocessor alone is not sufficient.
+
+### 3. Add TypeScript globals
+
+Add `svelte-origin/globals` to your `tsconfig.json` to enable types for `$origin`, `$origin.component`, etc.
+
+```json
+{
+	"compilerOptions": {
+		"types": [
+			"svelte-origin/globals"
+		]
+	}
+}
+```
+
+### Plugin options
+
+```ts
+svelteOrigin({
+	// File extensions for origin definitions
+	extensions: ['.svelte.ts', '.svelte.js', '.origin.svelte.ts'],
+	
+	// Enable debug logging
+	debug: false,
+	
+	// Output transformed code to .transformed.txt files for debugging
+	outputTransformed: false,
+	
+	// Directory for transformed output files (defaults to same as source)
+	// The directory will be created automatically if it doesn't exist.
+	// This setting is shared with the preprocessor, so both .svelte.ts and
+	// .svelte files will output to the same directory.
+	outputDir: undefined
+})
+```
+
+## The core idea
+
+### 1) Define an origin
+
+Write origins in a file where runes are allowed (e.g. `.svelte.ts`).
+
+```ts
+// counter.svelte.ts
+export const Counter = $origin({
+	props: $origin.props({
+		/** The label for the counter */
+		label: 'Counter',
+		/** The current count value (bindable for two-way binding) */
+		count: $bindable(0),
+		/** Step value for increment/decrement (optional) */
+		step: 1 as number
+	}),
+
+	/** Internal counter (private - not exposed) */
+	_incrementCount: $state(0),
+
+	/** Get double the current count */
+	get double() {
+		return $derived(this.props.count * 2)
+	},
+
+	/** Increment by step */
+	increment() {
+		this._incrementCount++
+		this.props.count += this.props.step
+	},
+
+	/** Decrement by step */
+	decrement() {
+		this.props.count -= this.props.step
+	},
+
+	/** Reset to zero */
+	reset() {
+		this.props.count = 0
+	}
+})
+```
+
+Notes:
+
+- `$origin(...)` is a **compile-time macro** provided by `svelte-origin` (not a Svelte rune)
+- `props: $origin.props({...})` defines the component props schema
+	- compiles into the origin's prop schema with defaults and bindable handling
+	- the property name (`props`) is the recommended convention
+- `$bindable(...)` inside `props: $origin.props({...})` marks props for two-way binding
+- `$state`/`$derived` are real Svelte runes
+- Properties prefixed with `_` (like `_incrementCount`) are private and not exposed on the instance type
+
+### 2) Create an instance from component props
+
+Inside a component, be explicit that the instance is derived from the component's props:
+
+```svelte
+<!-- CounterComponent.svelte -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	
+	// Create the counter instance from component props
+	let counter = $origin.component(Counter)
+</script>
+
+<div class="counter">
+	<h3>{counter.props.label}</h3>
+	<p>{counter.props.count}</p>
+	<p>Double: {counter.double}</p>
+	<div class="controls">
+		<button onclick={() => counter.decrement()}>-{counter.props.step}</button>
+		<button onclick={() => counter.reset()}>Reset</button>
+		<button onclick={() => counter.increment()}>+{counter.props.step}</button>
+	</div>
+</div>
+```
+
+Key points:
+
+- We do **not** rely on "calling `Counter()` magically reads `$props()`"
+- We make the props dependency explicit via `$origin.component(Counter)`
+- For manual type declarations, use `$origin.Props<typeof Counter>`
+
+Under the hood, the macro expands to canonical `$props()` usage, so the component's prop types remain inferable.
+
+## Passing to subcomponents
+
+The rule of thumb is:
+
+- each component owns its own origin instance
+- parents forward values via props
+
+We make forwarding ergonomic using `$origin.for(...)`. This helper forwards the intersection of the parent's props and the child's origin requirements.
+
+> ⚠️ **Note:** `$origin.for()` only works in `.svelte` files. It throws an error if used in `.svelte.ts` module files.
+
+```svelte
+<script lang='ts'>
+	let childProps = $origin.for(ChildOrigin)
+</script>
+
+<Child {...childProps} />
+```
+
+Notes:
+
+- `$origin.for(...)` is intentionally about forwarding **from `$props()`**, not from an origin instance
+
+## Wrapper components / element props
+
+If you’re forwarding attributes onto a native element, the type you want is an **attribute type**, not `HTMLInputElement`.
+
+Svelte’s recommended types live in `svelte/elements`.
+
+To make this ergonomic, we can provide:
+
+```svelte
+<script lang='ts'>
+	let inputProps = $origin.for('input')
+</script>
+
+<input {...inputProps} />
+```
+
+(`$origin.for` is a macro that expands to a typed `$props()` + rest pattern.)
+
+
+
+## Extending origins
+
+You can extend existing origins by passing them as an array in the first argument. To access the parent implementation, use `this.super`.
+
+```ts
+export const Counter = $origin({
+	// ... base implementation
+	increment() {
+		this.props.count += 1
+	}
+})
+
+export const SuperCounter = $origin([Counter], {
+	increment() {
+		// Call the parent implementation
+		this.super.increment()
+		console.log('Incremented!')
+	}
+})
+```
+
+## Programmatic Origin Creation
+
+Use `$origin.create()` to create origin instances **programmatically**. Unlike `$origin.component()`, this works **everywhere**:
+
+- ✅ `.svelte` component scripts
+- ✅ `.svelte.ts` / `.svelte.js` module files  
+- ✅ Inside `$origin()` init callbacks
+- ✅ Inside origin method bodies
+- ✅ Module scripts (`<script module>`)
+
+### Basic Usage
+
+```ts
+import { Counter } from './counter.svelte'
+
+// Create an origin instance with initial prop values
+const counter = $origin.create(Counter, { count: 10, step: 2 })
+
+// Reading props works
+counter.props.count       // ✅ Returns 10
+counter.increment()       // ✅ Methods work
+
+// Without props (uses defaults)
+const defaultCounter = $origin.create(Counter)
+```
+
+> **Note:** Props passed directly to `$origin.create()` are **read-only** (getter-only). If you need to set props externally, use `$origin.bind()` to create two-way bindings.
+
+### Binding to Existing State (Two-Way Reactivity)
+
+Use `$origin.bind()` to sync an origin's prop with an existing reactive variable. **This is the only way to get settable props** with `$origin.create()`:
+
+```ts
+let count = $state(10)
+
+const counter = $origin.create(Counter, {
+	count: $origin.bind(count)  // Two-way binding
+})
+
+// Both are now in sync:
+counter.props.count = 20    // ✅ count is now 20
+count = 5                   // counter.props.count is now 5
+counter.increment()         // ✅ Both update
+```
+
+Mix bound and unbound props as needed:
+
+```ts
+let sharedCount = $state(0)
+
+const counter = $origin.create(Counter, {
+	count: $origin.bind(sharedCount),  // Two-way (settable)
+	label: 'My Counter',               // Read-only
+	step: 2                            // Read-only
+})
+```
+
+### Why Not Call the Factory Directly?
+
+**Never call the factory directly** — it bypasses the transform and breaks reactivity:
+
+```ts
+// ❌ BAD - Bypasses macro transformation
+const counter = Counter({ count: 0 })
+// Props are plain object - no reactivity at all!
+
+// ✅ GOOD - Use $origin.create() for proper transformation
+const counter = $origin.create(Counter, { count: 0 })
+// Props are getter-based and can read from reactive sources
+```
+
+**To set props externally**, you must bind to a reactive variable:
+
+```ts
+let count = $state(0)
+
+const counter = $origin.create(Counter, { 
+	count: $origin.bind(count)  // Now settable!
+})
+
+counter.props.count = 5  // ✅ Works - updates `count` too
+```
+
+## Attachments
+
+Origins can define **attachment methods** that run when an element is attached to the DOM. These are methods prefixed with `$` that receive the element and optionally return a cleanup function.
+
+### Defining attachments
+
+```ts
+// widget.svelte.ts
+export const Widget = $origin({
+	props: $origin.props({
+		color: 'blue'
+	}),
+
+	/** Attachment: adds a tooltip to an element */
+	$tooltip(element: Element) {
+		const tooltip = document.createElement('div')
+		tooltip.textContent = 'Tooltip for ' + this.props.color
+		element.appendChild(tooltip)
+		
+		// Return cleanup function
+		return () => tooltip.remove()
+	},
+
+	/** Attachment: highlights the element */
+	$highlight(element: Element) {
+		element.classList.add('highlighted')
+		return () => element.classList.remove('highlighted')
+	}
+})
+```
+
+### Using attachments
+
+Spread `$attachments` onto any element to apply all defined attachment behaviors:
+
+```svelte
+<script lang="ts">
+	import { Widget } from './widget.svelte'
+	let widget = $origin.component(Widget)
+</script>
+
+<!-- All attachment methods are applied to this div -->
+<div {...widget.$attachments}>
+	Content with tooltip and highlight
+</div>
+```
+
+### Forwarding incoming attachments
+
+When a parent uses Svelte's `{@attach ...}` directive on your component, those attachments are automatically included in `$attachments`:
+
+```svelte
+<!-- Parent.svelte -->
+<WidgetComponent {@attach myCustomAttachment} />
+```
+
+```svelte
+<!-- WidgetComponent.svelte -->
+<script lang="ts">
+	import { Widget } from './widget.svelte'
+	let widget = $origin.component(Widget)
+</script>
+
+<!-- Both origin-defined AND incoming attachments are applied -->
+<div {...widget.$attachments}>...</div>
+```
+
+This enables composable attachment behavior where parents can add behaviors to child component elements.
+
+## Init Callbacks
+
+Origins support an optional init callback that runs when the origin instance is created:
+
+```ts
+export const Timer = $origin({
+	props: $origin.props({
+		interval: 1000
+	}),
+	
+	_count: $state(0),
+	
+	get count() {
+		return $derived(this._count)
+	}
+}, function() {
+	// Runs when the component is created
+	const id = setInterval(() => {
+		this._count++
+	}, this.props.interval)
+	
+	// Return cleanup function (runs on unmount)
+	return () => clearInterval(id)
+})
+```
+
+The callback:
+- Runs after the instance is created
+- Has access to `this` (the full instance including private members)
+- Can return a cleanup function that runs when the component is destroyed
+
+### Origins Without Props (State-Only Origins)
+
+Origins don't require props — you can define pure internal state:
+
+```ts
+// simple.svelte.ts
+export const SimpleCounter = $origin({
+	count: $state(0),
+	increment() { this.count++ },
+	decrement() { this.count-- },
+	reset() { this.count = 0 }
+})
+```
+
+### Creating Child Origins
+
+When an origin needs to create other origin instances, **always use `$origin.create()`**:
+
+```ts
+// Manager that creates child origins
+export const Manager = $origin({
+	name: $state('Manager'),
+	
+	// Pattern 1: Inline initialization
+	childCounter: $origin.create(SimpleCounter),
+	
+	// Pattern 2: Lazy initialization (typed with $origin.Of)
+	lazyChild: $state(undefined) as undefined | $origin.Of<typeof SimpleCounter>
+}, function() {
+	// Pattern 3: Init callback initialization - ALSO use $origin.create()
+	this.lazyChild = $origin.create(SimpleCounter)
+})
+```
+
+> **Critical:** Never call the factory directly (e.g., `SimpleCounter({})`). This loses reactivity. Always use `$origin.create()` — it gets transformed at compile time.
+
+### Type Utilities
+
+```ts
+import { Counter } from './counter.svelte'
+
+// Extract props type (for component prop declarations)
+type CounterProps = $origin.Props<typeof Counter>
+
+// Extract instance type (for variable declarations)
+type CounterInstance = $origin.Of<typeof Counter>
+let counter: $origin.Of<typeof Counter>
+```
+
+```svelte
+<script lang="ts">
+	import { SimpleCounter, Manager } from './simple.svelte'
+
+	// Create instances using $origin.create() for proper reactivity
+	const counter = $origin.create(SimpleCounter)
+	const manager = $origin.create(Manager)
+</script>
+
+<!-- SimpleCounter (no props) -->
+<p>count = {counter.count}</p>
+<button onclick={() => counter.increment()}>Increment</button>
+
+<!-- Manager (with child created in init) -->
+<p>manager.name = {manager.name}</p>
+{#if manager.childCounter}
+	<p>childCounter.count = {manager.childCounter.count}</p>
+	<button onclick={() => manager.childCounter?.increment()}>Increment Child</button>
+{/if}
+```
+
+### `$origin.component()` vs `$origin.create()`
+
+| | `$origin.component()` | `$origin.create()` |
+|---|---|---|
+| **Use in** | `.svelte` files only | ✅ Everywhere |
+| **Props source** | Component's `$props()` | Passed explicitly or omitted |
+| **Prop mutability** | Bindable props are settable | Read-only unless using `$origin.bind()` |
+| **Two-way binding** | Tied to parent via `$bindable()` props | Use `$origin.bind(variable)` |
+| **Typical use** | Component state management | Child origins, tests, modules |
+| **Module file behavior** | ❌ Throws error | ✅ Works |
+
+```svelte
+<!-- Component: uses $origin.component() -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	
+	// Props flow from parent component → origin instance
+	let counter = $origin.component(Counter)
+</script>
+```
+
+```ts
+// Origin file: uses $origin.create()
+import { SimpleCounter } from './simple.svelte'
+
+export const Manager = $origin({
+	// Child is an independent reactive instance
+	child: $origin.create(SimpleCounter)
+})
+```
+
+## Origin Destructuring
+
+Destructure methods and props from origin instances with automatic handling:
+
+### Method Destructuring
+
+Methods are automatically bound to preserve `this` context:
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	let counter = $origin.component(Counter)
+	
+	// Destructure methods - automatically bound
+	let { increment, decrement } = counter
+</script>
+
+<button onclick={increment}>+</button>
+<button onclick={decrement}>-</button>
+```
+
+### Props Destructuring
+
+Props are automatically wrapped in `$derived` for reactivity:
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	let counter = $origin.component(Counter)
+	
+	// Destructure props - automatically reactive
+	let { count, label } = counter.props
+</script>
+
+<p>{label}: {count}</p>
+```
+
+### Nested Destructuring
+
+Combine method and props destructuring:
+
+```svelte
+<script lang="ts">
+	let { increment, props: { count, label } } = counter
+</script>
+```
+
+### Aliases and Defaults
+
+```svelte
+<script lang="ts">
+	let { increment: inc } = counter
+	let { count: counterValue = 0 } = counter.props
+</script>
+```
+
+## CLI (Library Authors)
+
+For library authors, the CLI transforms macros in `svelte-package` output and **eliminates the svelte-origin runtime dependency**.
+
+### Zero-Dependency Output (Default)
+
+By default, the CLI inlines the minimal runtime (~4KB minified) into your library's dist folder:
+
+```bash
+svelte-package && svelte-origin
+```
+
+This means **your library consumers only need Svelte** - no svelte-origin dependency required. The CLI:
+
+1. Transforms any remaining macros in the dist output
+2. Replaces `svelte-origin/runtime` imports with a local inline runtime
+3. Writes `__svelte-origin-runtime.js` to your dist folder
+
+### Keeping svelte-origin as Dependency
+
+If you want consumers to use the full svelte-origin package (e.g., for advanced features or smaller bundle size when multiple libraries use svelte-origin), use `--dependency`:
+
+```bash
+svelte-package && svelte-origin --dependency
+```
+
+### CLI Options
+
+```bash
+svelte-origin [command] [options]
+
+Commands:
+  post-process  Post-process svelte-package output (default)
+  generate-dts  Generate .svelte.d.ts files for svelte-check
+  help          Show help for a command
+
+Post-process options:
+  -h, --help       Show help
+  -n, --dry-run    Show what would be transformed without writing
+  -v, --verbose    Show detailed transformation info
+  -d, --dependency Keep svelte-origin as a runtime dependency (skip inlining)
+
+Examples:
+  svelte-package && svelte-origin                    # Default: inline runtime
+  svelte-package && svelte-origin dist               # Specify directory
+  svelte-package && svelte-origin --dependency       # Keep dependency
+  svelte-origin help post-process                    # Show post-process help
+```
+
+## License
+
+MIT