tutuca 0.15.0 → 1.0.0-beta.2

package/src/dev/vdom-formatters.js

@@ -0,0 +1,102 @@
+// DevTools custom formatters for vdom trees (Chrome/Firefox), shown like the Elements panel.
+import { HTML_NS, VBase, VComment, VFragment, VNode, VText } from "../vdom.js";
+import { install, makeFormatter, objectRef as ref, span, truncate } from "./jsonml.js";
+
+const S = {
+	tag: "color:#9333ea",
+	attr: "color:#d97706",
+	str: "color:#16a34a",
+	muted: "opacity:0.6",
+	removed: "opacity:0.6;text-decoration:line-through",
+};
+const MAX_STR = 40;
+const MAX_INLINE_ATTRS = 4;
+
+const quoted = (s) => span(S.str, JSON.stringify(truncate(s, MAX_STR)));
+
+// every stops at the first non vnode, so big arrays of other things bail out on item 0.
+const isVdomArray = (v) => Array.isArray(v) && v.length > 0 && v.every((c) => c instanceof VBase);
+
+const tagName = (node) => {
+	const implicit = node.namespace === null || node.namespace === HTML_NS;
+	if (implicit || node.tag === "svg" || node.tag === "math") return node.tag;
+	return `${node.namespace.split("/").at(-1).toLowerCase()}:${node.tag}`; // e.g. svg:circle
+};
+
+const attrParts = (name, value) => {
+	if (value === true) return [" ", span(S.attr, name)];
+	if (value === false || value == null) return [" ", span(S.removed, `${name}=${value}`)];
+	if (typeof value === "function") return [" ", span(S.muted, `${name}=ƒ`)];
+	if (typeof value === "object") return [" ", span(S.attr, name), "=", ref(value)];
+	return [" ", span(S.attr, name), "=", quoted(String(value))];
+};
+const keyParts = (key) => (key === undefined ? [] : [" ", span(S.muted, `key="${key}"`)]);
+
+const openTag = (node) => {
+	const names = Object.keys(node.attrs);
+	const parts = [span(S.tag, `<${tagName(node)}`), ...keyParts(node.key)];
+	for (const name of names.slice(0, MAX_INLINE_ATTRS)) {
+		parts.push(...attrParts(name, node.attrs[name]));
+	}
+	if (names.length > MAX_INLINE_ATTRS) {
+		parts.push(" ", span(S.muted, `…+${names.length - MAX_INLINE_ATTRS}`));
+	}
+	parts.push(span(S.tag, ">"));
+	return parts;
+};
+const closeTag = (node) => span(S.tag, `</${tagName(node)}>`);
+// A lone short text child renders inline, like the Elements panel does.
+const inlineText = (node) => {
+	const [child] = node.childs;
+	return node.childs.length === 1 && child instanceof VText && child.text.length <= MAX_STR
+		? child
+		: null;
+};
+
+const vdomFormatter = (comment) => {
+	const commentParts = (node) => comment?.(node.text) ?? [span(S.muted, `<!--${node.text}-->`)];
+	const describe = (v) => {
+		if (v instanceof VNode) {
+			const text = inlineText(v);
+			if (v.childs.length === 0 || text !== null) {
+				const inner = text === null ? [] : [text.text];
+				return { header: [...openTag(v), ...inner, closeTag(v)], childs: [] };
+			}
+			return {
+				header: [...openTag(v), span(S.muted, "…"), closeTag(v)],
+				childs: v.childs,
+				close: closeTag(v),
+			};
+		}
+		if (v instanceof VText) return { header: [quoted(v.text)], childs: [] };
+		if (v instanceof VComment) return { header: commentParts(v), childs: [] };
+		if (v instanceof VFragment) {
+			return {
+				header: [span(S.tag, "<>"), ...keyParts(v.key), span(S.muted, ` (${v.childs.length})`)],
+				childs: v.childs,
+				close: span(S.tag, "</>"),
+			};
+		}
+		if (isVdomArray(v)) {
+			const noun = v.length === 1 ? "vnode" : "vnodes";
+			return { header: [span(S.muted, `[${v.length} ${noun}]`)], childs: v };
+		}
+		return null;
+	};
+	return makeFormatter({
+		header: (v) => describe(v)?.header ?? null,
+		rows(v) {
+			const d = describe(v);
+			if (d === null || d.childs.length === 0) return [];
+			const rows = d.childs.map((c) => ["li", {}, ref(c)]);
+			if (d.close !== undefined) rows.push(["li", {}, d.close]);
+			return rows;
+		},
+	});
+};
+
+const installed = new WeakMap(); // target → formatter, so installing twice is a no-op
+export const installVdomFormatters = (target = globalThis, { comment } = {}) => {
+	if (!installed.has(target)) installed.set(target, install(target, vdomFormatter(comment)));
+	return installed.get(target);
+};

package/src/drag.js

@@ -0,0 +1,23 @@
+// Drag and drop: the drag the host keeps from dragstart to dragend, read by handlers as ctx.drag.
+
+// The events over a drop target. They reach the nearest enclosing component that handles them,
+// so a drop on a child's elements gets to the parent's on:drop.
+export const DROP_EVENTS = new Set(["dragenter", "dragover", "dragleave", "drop"]);
+// What the host listens to once a component handles drop.
+export const DRAG_EVENTS = ["dragstart", "dragend", ...DROP_EVENTS];
+
+// The element being dragged: where it was rendered, its data-dragtype and the value there
+// when the drag started.
+export class Drag {
+	constructor(path, type, node, value) {
+		this.path = path;
+		this.type = type;
+		this.node = node;
+		this.value = value;
+	}
+	// The key of the child of receiver the dragged element is in, as sourceKey is for a
+	// message; null when it was dragged from outside receiver.
+	keyIn(receiver) {
+		return this.path.sourceKeyIn(receiver);
+	}
+}

package/src/embed/element.js

@@ -0,0 +1,111 @@
+// An isolated tutuca app inside another: <tutuca-app app-key="..."> asks its ancestors for
+// an app to mount in its shadow root. The outer render never morphs shadow content and
+// events leaving it are retargeted to the element, so the outer Host never sees inside.
+//
+// Protocol, both as bubbling CustomEvents on the element:
+// - REQUEST, on connect and when app-key changes. Its detail is { key, element, rootNode,
+//   document, adoptCss(text) → <style>, adoptLink(href), emit(type, data), mount(controller) }; a
+//   listener mounts an app on rootNode and passes mount a controller with dispose().
+// - REPORT, sent by emit, with detail { key, type, data }. An outer view can handle it
+//   like any event: h("tutuca-app", { "app-key": ..., "on:tutucareport": send(...) }).
+//   Reports go out in a microtask, in order: a request answered during the outer render,
+//   or a call from an outer task, never reenters the outer Host.
+// The outer side calls the app through element.controller or its own registry by key.
+import { Host } from "../tutuca.js";
+
+export const REQUEST = "tutucarequest";
+export const REPORT = "tutucareport";
+
+// Defines the element in window once; returns its class.
+export const defineTutucaApp = (window, tagName = "tutuca-app") => {
+	const existing = window.customElements.get(tagName);
+	if (existing !== undefined) return existing;
+	class TutucaApp extends window.HTMLElement {
+		static observedAttributes = ["app-key"];
+		controller = null;
+		mountedKey = null;
+		current = null; // The detail of the live request; emits from older ones are dropped.
+		get key() {
+			return this.getAttribute("app-key");
+		}
+		// A keyed move (insertBefore) disconnects and reconnects; keep the app through it.
+		connectedCallback() {
+			if (this.current === null || this.mountedKey !== this.key) this.request();
+		}
+		disconnectedCallback() {
+			queueMicrotask(() => {
+				if (!this.isConnected) this.dispose();
+			});
+		}
+		attributeChangedCallback() {
+			if (this.isConnected) this.request();
+		}
+		request() {
+			this.dispose();
+			const doc = this.ownerDocument;
+			const shadow = this.shadowRoot ?? this.attachShadow({ mode: "open" });
+			const rootNode = doc.createElement("div");
+			shadow.replaceChildren(rootNode);
+			const key = this.key;
+			let controller = null;
+			const detail = {
+				key,
+				element: this,
+				rootNode,
+				document: doc,
+				adoptCss: (text) => {
+					const style = doc.createElement("style");
+					style.textContent = text;
+					shadow.insertBefore(style, rootNode);
+					return style; // To update as the app needs more.
+				},
+				adoptLink: (href) => {
+					const link = doc.createElement("link");
+					link.rel = "stylesheet";
+					link.href = href;
+					shadow.insertBefore(link, rootNode);
+				},
+				emit: (type, data) =>
+					queueMicrotask(() => {
+						if (this.current !== detail) return;
+						const init = { bubbles: true, detail: { key, type, data } };
+						this.dispatchEvent(new window.CustomEvent(REPORT, init));
+					}),
+				mount: (c) => {
+					controller = c;
+				},
+			};
+			this.current = detail;
+			this.mountedKey = key;
+			this.dispatchEvent(new window.CustomEvent(REQUEST, { bubbles: true, detail }));
+			if (controller === null) rootNode.textContent = `no app for ${key}`;
+			this.controller = controller;
+		}
+		dispose() {
+			const { controller } = this;
+			this.controller = null;
+			this.current = null;
+			this.mountedKey = null;
+			controller?.dispose();
+		}
+	}
+	window.customElements.define(tagName, TutucaApp);
+	return TutucaApp;
+};
+
+// Mounts a plain Host for a request: register(scope) registers its components, make(C)
+// makes the root from them. Returns the controller, already passed to detail.mount.
+export const mountTutucaApp = (detail, { register, make, dev = false, onNotify }) => {
+	const host = new Host({ document: detail.document, rootNode: detail.rootNode, dev });
+	register(host.scope);
+	if (onNotify !== undefined) host.onNotify = onNotify;
+	host.start(make(host.scope.components));
+	const controller = {
+		host,
+		dispose() {
+			host.stop();
+		},
+	};
+	detail.mount(controller);
+	return controller;
+};

package/src/env.js

@@ -0,0 +1,30 @@
+// What handlers read from the world, through ctx.now(), ctx.random() and ctx.uuid(): the
+// clock in ms since the epoch, a number in [0, 1) and a new id. Each mirrors the global it
+// stands for, so a host can swap them for ones that repeat (testEnv).
+export const browserEnv = {
+	now: () => Date.now(),
+	random: () => Math.random(),
+	uuid: () => globalThis.crypto.randomUUID(),
+};
+// An env whose runs repeat: a clock stopped at start until advance(ms) moves it, numbers from
+// a generator seeded with seed, and uuid-shaped ids that count up.
+export const testEnv = ({ seed = 1, start = Date.UTC(2026, 0, 1) } = {}) => {
+	let time = start;
+	let state = seed >>> 0;
+	let ids = 0;
+	return {
+		now: () => time,
+		advance(ms) {
+			time += ms;
+		},
+		// mulberry32
+		random() {
+			state = (state + 0x6d2b79f5) >>> 0;
+			let x = state;
+			x = Math.imul(x ^ (x >>> 15), x | 1);
+			x ^= x + Math.imul(x ^ (x >>> 7), x | 61);
+			return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
+		},
+		uuid: () => `00000000-0000-4000-8000-${(++ids).toString(16).padStart(12, "0")}`,
+	};
+};

package/src/events.js

@@ -0,0 +1,85 @@
+// DOM events: finds the component, path and handlers an event belongs to from the meta comments.
+import { isMetaOpen, META_CLOSE, parseMeta } from "./meta.js";
+import { Address, DispatchPath, Frame } from "./paths.js";
+import { specOf } from "./schema.js";
+
+const META_TYPES = new Set(["component", "frame"]);
+function* enclosingNodeMeta(node) {
+	let closed = 0;
+	for (let n = node.previousSibling; n; n = n.previousSibling) {
+		if (n.nodeType !== 8) continue;
+		const data = n.data;
+		if (data === META_CLOSE) {
+			closed++;
+			continue;
+		}
+		if (!isMetaOpen(data)) continue;
+		if (closed > 0) {
+			closed--;
+			continue;
+		}
+		let meta;
+		try {
+			meta = parseMeta(data);
+		} catch (err) {
+			console.error("bad meta comment", err, n, node);
+			continue;
+		}
+		if (META_TYPES.has(meta?.t)) yield meta; // Skip look-alike comments from unmanaged DOM.
+	}
+}
+// From node up to rootNode: the metas, innermost first; where each component meta is in them;
+// and the elements with handlers, each with the number of components below it. null when
+// node is outside rootNode.
+const walkUp = (node, rootNode) => {
+	const metas = [];
+	const components = [];
+	const eids = [];
+	while (node && node !== rootNode) {
+		// The attribute, not dataset, which elements outside HTML and SVG (MathML in jsdom) lack.
+		const eid = node.getAttribute?.("data-eid");
+		if (eid != null) eids.push({ eid: parseInt(eid, 10), node, level: components.length });
+		for (const meta of enclosingNodeMeta(node)) {
+			if (meta.t === "component") components.push(metas.length);
+			metas.push(meta);
+		}
+		node = node.parentNode;
+	}
+	return node === rootNode ? { metas, components, eids } : null;
+};
+// The path the metas, innermost first, describe.
+const pathFrom = (metas) => {
+	const frames = [];
+	for (const meta of [...metas].reverse()) {
+		if (meta.t === "frame") frames.push(Frame.fromMeta(meta));
+		else if (frames.length > 0) frames.push(frames.pop().asComponent());
+	}
+	return new DispatchPath(frames);
+};
+// The path of the component, and the loop items in it, node was rendered in.
+export const pathOf = (node, rootNode) => {
+	const walk = walkUp(node, rootNode);
+	return walk === null || walk.components.length === 0 ? null : pathFrom(walk.metas);
+};
+// The handler for a type event on target, with the address of its component and its element.
+// Only the component target is in handles it, unless bubbles: then the nearest enclosing
+// component with a handler for it does.
+export const getEventInfoFor = (target, type, rootNode, rootComponent, bubbles = false) => {
+	const walk = walkUp(target, rootNode);
+	if (walk === null) return null;
+	const levels = bubbles ? walk.components.length : Math.min(1, walk.components.length);
+	for (let level = 0; level < levels; level++) {
+		const eids = walk.eids.filter((e) => e.level === level);
+		if (eids.length === 0) continue;
+		// What is outside the component below: its frame is the child the event came through.
+		const start = level === 0 ? 0 : walk.components[level - 1] + 1;
+		const to = Address.at(pathFrom(walk.metas.slice(start)), rootComponent);
+		const { eventHandlers } = specOf(to.updatePath.getIn(rootComponent));
+		for (const { eid, node } of eids) {
+			for (const handler of eventHandlers.get(eid) ?? []) {
+				if (handler.name === type) return { handler, to, node };
+			}
+		}
+	}
+	return null;
+};

package/src/history/bar.js

@@ -0,0 +1,198 @@
+// The time travel bar: ⏮ ◀ ▶ ⏭, a slider over the states and what made the current one. It
+// holds no timeline, it shows the one it's given and asks "history" to move through it, with
+// [target, op, arg], op one of goto, back, forward, toStart and toEnd. mountTimeTravel puts
+// one, with a historyEngine, next to a live Host.
+
+import { ORIGINS } from "../storybook/ui/common.js";
+import {
+	$if,
+	button,
+	component,
+	DispatchPath,
+	field,
+	HOST,
+	Host,
+	send,
+	Target,
+	Task,
+	t,
+	tag,
+	targetValue,
+} from "../tutuca.js";
+import { historyEngine } from "./index.js";
+
+const { div, input, span } = tag;
+
+const OPS = ["goto", "back", "forward", "toStart", "toEnd"];
+const BUTTON = "btn btn-xs btn-ghost font-mono";
+const KEYS = { ArrowLeft: "back", ArrowRight: "forward", Home: "toStart", End: "toEnd" };
+
+export const TimeTravel = component({
+	name: "TimeTravel",
+	fields: {
+		target: t.string(), // Passed along with each op: the app the timeline belongs to.
+		size: t.number().int().min(0),
+		cursor: t.number().int().min(0),
+		label: t.string(),
+		origin: t.string(),
+	},
+	methods: {
+		// One state is not a history to travel through.
+		get isShown() {
+			return this.size > 1;
+		},
+		get last() {
+			return Math.max(0, this.size - 1);
+		},
+		get atStart() {
+			return this.cursor === 0;
+		},
+		get atEnd() {
+			return this.cursor >= this.last;
+		},
+		get position() {
+			return `state ${this.cursor + 1} of ${this.size}`;
+		},
+		get icon() {
+			return ORIGINS[this.origin] ?? "";
+		},
+	},
+	view: $if(
+		field("isShown"),
+		div(
+			{
+				class: "flex w-full items-center gap-2 text-sm",
+				role: "group",
+				"aria-label": "Time travel",
+				title: "Alt+← and Alt+→ step back and forward",
+				"on:keydown": send("key"),
+			},
+			button(
+				{
+					class: BUTTON,
+					title: "First state",
+					disabled: field("atStart"),
+					"on:click": send("op", "toStart"),
+				},
+				"⏮",
+			),
+			button(
+				{
+					class: BUTTON,
+					title: "Back",
+					disabled: field("atStart"),
+					"on:click": send("op", "back"),
+				},
+				"◀",
+			),
+			button(
+				{
+					class: BUTTON,
+					title: "Forward",
+					disabled: field("atEnd"),
+					"on:click": send("op", "forward"),
+				},
+				"▶",
+			),
+			button(
+				{
+					class: BUTTON,
+					title: "Last state",
+					disabled: field("atEnd"),
+					"on:click": send("op", "toEnd"),
+				},
+				"⏭",
+			),
+			input({
+				type: "range",
+				class: "range range-xs range-primary w-64 max-w-[40vw] shrink-0",
+				"aria-label": "State",
+				min: "0",
+				max: field("last"),
+				value: field("cursor"),
+				"on:input": send("goto", targetValue()),
+			}),
+			span(
+				{ class: "min-w-0 flex-1 truncate font-mono text-xs tabular-nums opacity-70" },
+				field("position"),
+				" · ",
+				field("icon"),
+				" ",
+				field("label"),
+			),
+		),
+		"",
+	),
+	on: {
+		show: {
+			args: [t.number().int().min(0), t.number().int().min(0), t.string(), t.string()],
+			run(next, [size, cursor, label, origin]) {
+				Object.assign(next, { size, cursor, label, origin });
+			},
+		},
+		op: {
+			args: [t.enum(...OPS)],
+			emits: { ask: ["history"] },
+			run(_next, [op], ctx) {
+				ctx.ask("history", [this.target, op, null]);
+			},
+		},
+		goto: {
+			args: [t.string()],
+			emits: { ask: ["history"] },
+			run(_next, [value], ctx) {
+				const i = Number(value);
+				if (Number.isInteger(i)) ctx.ask("history", [this.target, "goto", i]);
+			},
+		},
+		// Alt+← and Alt+→ step, Alt+Home and Alt+End jump to the ends.
+		key: {
+			args: [],
+			emits: { ask: ["history"] },
+			run(_next, _args, ctx) {
+				const op = ctx.event?.altKey ? KEYS[ctx.event.key] : undefined;
+				if (op === undefined) return;
+				ctx.event.preventDefault?.();
+				ctx.ask("history", [this.target, op, null]);
+			},
+		},
+	},
+	answers: {
+		history: {
+			ok() {},
+			error(_next, [error]) {
+				console.error("time travel failed", error);
+			},
+		},
+	},
+});
+
+// What the bar shows of a Timeline, as the args of its show message.
+export const showArgs = ({ size, cursor, current }) => [
+	size,
+	cursor,
+	current?.label ?? "",
+	current?.origin ?? "",
+];
+// Sends name(...args) to host's root component from outside the app.
+const sendRoot = (host, name, args) => {
+	const task = new Task(name, args, HOST, new Target(new DispatchPath()), null);
+	task.prepare(host.rootComponent);
+	host.pushTask(task);
+};
+
+// Records host's timeline with a historyEngine of at most max states and shows a TimeTravel
+// bar for it in rootNode, on a Host of its own; returns { engine, bar, stop }.
+export const mountTimeTravel = ({ document, rootNode, host, max = 1000 }) => {
+	const bar = new Host({ document, rootNode });
+	bar.scope.register({ TimeTravel });
+	// A message, not a new root: travel runs while the bar handles its ask.
+	const show = (timeline) => sendRoot(bar, "show", showArgs(timeline));
+	const engine = historyEngine({ max, onChange: show });
+	bar.scope.registerAskHandlers({
+		history: ([_target, op, arg]) => (op === "goto" ? engine.travel(arg) : engine[op]()),
+	});
+	bar.start(bar.scope.components.TimeTravel());
+	host.attachSync(engine);
+	return { engine, bar, stop: () => bar.stop() };
+};

package/src/history/index.js

@@ -0,0 +1,149 @@
+// Time travel: a Timeline of states with a cursor, and historyEngine, which records one for a
+// live Host as a sync engine and travels by applying a recorded state as a change from
+// elsewhere, so the other engines (storage, peers) follow.
+
+import { truncate } from "../dev/jsonml.js";
+import { jsonText } from "../paths.js";
+import { EventTask } from "../tasks.js";
+
+export const argsLabel = (args) => truncate(args.map(jsonText).join(", "), 80);
+// The task a task's chain started with: an event, or a message sent from outside.
+export const rootTask = (task) => {
+	while (task.parent !== null) task = task.parent;
+	return task;
+};
+// A task as a timeline shows it, like "click → toggle()".
+export const taskLabel = (task) => {
+	const call = `${task.name}(${argsLabel(task.args)})`;
+	return task instanceof EventTask ? `${task.event.type} → ${call}` : call;
+};
+
+// The left entry of the two closest in time, the one to drop to keep the rest spread out,
+// sparing the first and the current; -1 when every one is spared.
+const closestLeft = (entries, cursor) => {
+	let found = -1;
+	let closest = Infinity;
+	for (let i = 2; i < entries.length; i++) {
+		const left = i - 1;
+		if (left === cursor) continue;
+		const gap = entries[i].at - entries[left].at;
+		// <= drops the most recent of equally close pairs, keeping older ones.
+		if (gap <= closest) {
+			closest = gap;
+			found = left;
+		}
+	}
+	return found;
+};
+
+// States in order, entries { state, label, origin, at, ... }, and a cursor at the one shown.
+// Recording after going back drops the entries after the cursor. Past max entries it drops
+// one of the two closest in time, so a burst of changes thins out but the history keeps its
+// spread; the first entry and the current one stay.
+export class Timeline {
+	constructor({ max = 1000, now = Date.now } = {}) {
+		this.max = max;
+		this.now = now;
+		this.entries = [];
+		this.cursor = 0;
+	}
+	get size() {
+		return this.entries.length;
+	}
+	get current() {
+		return this.entries[this.cursor];
+	}
+	get atEnd() {
+		return this.cursor === this.entries.length - 1;
+	}
+	begin(entry) {
+		this.entries = [{ at: this.now(), ...entry }];
+		this.cursor = 0;
+		return this.current;
+	}
+	record(entry) {
+		this.entries.length = this.cursor + 1;
+		this.entries.push({ at: this.now(), ...entry });
+		this.cursor = this.entries.length - 1;
+		while (this.entries.length > this.max) {
+			const i = closestLeft(this.entries, this.cursor);
+			if (i < 0) break;
+			this.entries.splice(i, 1);
+			if (i < this.cursor) this.cursor--;
+		}
+		return this.current;
+	}
+	// Folds task into the current entry when it's the last one and task continues the chain
+	// that made it, as async replies do; false when task starts an entry of its own.
+	merge(task, state) {
+		const entry = this.current;
+		if (!this.atEnd || entry?.rootTask === undefined || entry.rootTask !== rootTask(task)) {
+			return false;
+		}
+		entry.state = state;
+		entry.tasks = [...(entry.tasks ?? []), task];
+		return true;
+	}
+	goto(i) {
+		this.cursor = Math.max(0, Math.min(Number(i), this.entries.length - 1));
+		return this.current;
+	}
+	back() {
+		return this.goto(this.cursor - 1);
+	}
+	forward() {
+		return this.goto(this.cursor + 1);
+	}
+	toStart() {
+		return this.goto(0);
+	}
+	toEnd() {
+		return this.goto(this.entries.length - 1);
+	}
+}
+
+// Records the timeline of the Host it's attached to (host.attachSync(engine)): one entry per
+// user action, its async replies folded in, and one per change from another engine. The
+// first entry is the state before the first change. travel(i) clears the queued tasks and
+// applies entry i as a change from this engine, so it isn't recorded and every other engine
+// sees it; an async reply that lands after it starts a new branch from there. onChange gets
+// the timeline after each change and travel.
+export const historyEngine = ({ max = 1000, now = Date.now, onChange = () => {} } = {}) => {
+	const timeline = new Timeline({ max, now });
+	let link = null;
+	const seed = (state) => {
+		if (timeline.size === 0) timeline.begin({ state, label: "initial", origin: "initial" });
+	};
+	const travel = (move) => {
+		if (link === null || timeline.size === 0) return;
+		const { state } = move();
+		link.host.clearTasks();
+		link.apply(() => state);
+		onChange(timeline);
+	};
+	return {
+		timeline,
+		attach(l) {
+			link = l;
+		},
+		detach() {
+			link = null;
+		},
+		commit({ prev, next, task }) {
+			seed(prev);
+			if (task === null) {
+				timeline.record({ state: next, label: "synced change", origin: "external" });
+			} else if (!timeline.merge(task, next)) {
+				const root = rootTask(task);
+				const label = taskLabel(root);
+				timeline.record({ state: next, label, origin: "user", rootTask: root, tasks: [task] });
+			}
+			onChange(timeline);
+		},
+		travel: (i) => travel(() => timeline.goto(i)),
+		back: () => travel(() => timeline.back()),
+		forward: () => travel(() => timeline.forward()),
+		toStart: () => travel(() => timeline.toStart()),
+		toEnd: () => travel(() => timeline.toEnd()),
+	};
+};