I'll probably need to run into this a few times before it sinks into my finger tips...but I get it.

You could guess to write the output once you understand that property accesses in context register dependencies. Like in SolidJS or Preact.

export default function Doubler($$anchor, $$props) {
	$.push($$props, true);
	let doubler = expensiveCreateDoubler({ value: () => $$props.value });
	...

The input I feel like I have to "just know" what the output might in order to reason about the signal dependencies. It's not guessable.

let { value } = $props();
let doubler = expensiveCreateDoubler({ value: () => value });

For example, I imagine that LLMs might struggle with coming up with this as a solution when presented with the problem.

Using $effect can be OK when dealing with properties

As a note to self, if you must use an effect, you should probably use $effect.pre, since the $effect for properties would run after the DOM update, so it would need an extra DOM update for the changes caused by the $effect.

Documenting my updated thoughts. You may fact-check my thinking.

This is like the case of controlled vs uncontrolled components & props vs state.

• Controlled components receive their state from their parent. They may request changes to that data but they don't actually control it.

<button onclick={() => $$props.pleaseChangeCount($$props.count   1)}>
    {$$props.count}
</button>

• Uncontrolled components own their data and modify it directly.

For example, a devout follower of the controlled component religion would "fix" the read-write example so that you're more explicit about changing data you don't own. This might also reduce the probability that consumers instinctively try to expensiveCreateDoubler({ value }).

export function expensiveCreateDoubler(options) {
	let double = $derived(options.value * 2);

	return {
		get value() {
			return options.value;
		},
		set value(value) {
			options.prettyPleaseChangeValue(value);
		},
		get double() {
			return double;
		}
	}
}

It seems like in order to use the reactive object pattern (e.g. in a headless library), for some input values you must account for or even require a controlled reactive object in order to accommodate the case where the input value is passed down directly from props as in the OP...because while other state updates are typically associated with some event handler, there's of course no propchange event. Svelte makes this strategy a bit hard because there's no Signal<type> type that you can use to enforce this since signals are transparent.

export interface ControlledDoublerOptions {
    readonly value: number;
    prettyPleaseChangeValue(value: number): void;
}

Alternatively, you could create an uncontrolled reactive object, like I had done (and I imagine most people would first try to do)...where the consumer may need to use $effect.pre to update its properties for inputs that come from $props.

I'm leaning towards the uncontrolled objects effect direction. It has a better progressive disclosure of complexity:

• The onpropchange situation is less common and you shouldn't be penalized until you run into it later and learn about the need for $effect.pre.
• Consumers don't need to immediately understand the implementation of expensiveCreateDoubler i.e. know which values must, can or shouldn't be reactive. They can check the implementation/docs later when they need to update a specific value.

Never heard of or used this "controlled vs uncontrolled" distinction, not sure it's all that useful 🤔.

The get/set pair property is a bit opaque, but I think that at least for the read-only case, passing a function is pretty straightforward (here the intent will also be more apparent from the type).

I have seen advocacy for splitting the setter into a separate function, but this comes with drawbacks, e.g. the property can no longer be used with bind: syntax, and if the get part is not an accessor/function, you need to update the value separately.

Personally, I would rather use some option naming convention or make requirements/usage clear in the documentation which should be easily accessible directly in the IDE. It may still be a bit too early to tell what the best practice should be.