@rasamjs/core 0.2.0 → 0.3.0

package/src/changes/restore.ts

@@ -1,9 +1,11 @@
 import type { AnyNode } from '../core/types.js';
 import type { ParentNode } from '../mixins/types.js';
 import { destroySubtrees } from '../core/destruction.js';
-import { validateChild } from '../mixins/parent-internals.js';
+import { validateChild, withInternalStructure } from '../mixins/parent-internals.js';
 import { readTransformState } from '../mixins/transform-state.js';
 import { referenceValue } from '../services/reference-value.js';
+import { initializeNode } from '../services/initialization.js';
+import { isDerivedChange, ownsDerived } from './derived.js';
 import { captureState, sameState, stateAdapter, combineChanges } from './state.js';
 import {
   ChangeConflictError,
@@ -28,6 +30,14 @@ function currentValue(snapshot: ModelSnapshot | null, change: ModelChange): unkn
   return snapshot[change.domain];
 }
 
+/** An owner's derived child list is redrawn, not restored, so conflicts ignore it. */
+function comparable(value: unknown, change: ModelChange): unknown {
+  const snapshot = value as ModelSnapshot | null;
+  return change.domain === 'existence' && snapshot && ownsDerived(snapshot.constructor)
+    ? { ...snapshot, children: undefined }
+    : value;
+}
+
 function contentFeatures(content: ContentState): ModelFeatures['content'] {
   return {
     parts: content.parts.map((part) => (typeof part === 'string' ? part : part.node)),
@@ -80,7 +90,8 @@ function applyChanges(
   direction: 'undo' | 'redo',
 ): void {
   const service = owner.context.changes;
-  changes = combineChanges(changes);
+  // An owner redraws its derived children after replay, from the state replay restored.
+  changes = combineChanges(changes).filter((change) => !isDerivedChange(change));
   service.resetOrders();
   service.configure(stateAdapter);
   try {
@@ -97,7 +108,8 @@ function applyChanges(
         domains.set(change.target, new Set());
       }
       const expected = direction === 'undo' ? change.after : change.before;
-      if (!sameState(currentValue(before.get(change.target)!, change), expected))
+      const current = currentValue(before.get(change.target)!, change);
+      if (!sameState(comparable(current, change), comparable(expected, change)))
         throw new ChangeConflictError(
           `Conflicting ${change.domain} state on node ${change.target.id}`,
         );
@@ -176,7 +188,7 @@ function validateGraph(
   const removed = new Set([...states].filter(([, state]) => !state).map(([target]) => target.node));
   for (const [target, state] of states) {
     if (!state) continue;
-    if (context.registry.get(state.constructor.tag) !== state.constructor)
+    if (context.registry.registered(state.constructor) !== state.constructor)
       throw new ChangeConflictError(`Constructor is not registered: ${state.constructor.tag}`);
     const id = state.properties.id?.value;
     if (
@@ -258,10 +270,19 @@ function validateGraph(
       throw new ChangeConflictError('A removed node would retain live typed references');
 }
 
+/** Replay restores exact prior trees, including children that their class owns. */
 function applyPrepared(
   owner: AnyNode,
   states: Map<NodeHandle, ModelSnapshot | null>,
   domains: Map<NodeHandle, Set<string>>,
+): void {
+  withInternalStructure(() => applyStates(owner, states, domains));
+}
+
+function applyStates(
+  owner: AnyNode,
+  states: Map<NodeHandle, ModelSnapshot | null>,
+  domains: Map<NodeHandle, Set<string>>,
 ): void {
   const context = owner.context;
   const recreated = new Set<NodeHandle>();
@@ -343,6 +364,7 @@ function applyPrepared(
   for (const [target, state] of states)
     if (
       state?.children &&
+      !ownsDerived(state.constructor) &&
       (recreated.has(target) ||
         domains.get(target)!.has('children') ||
         domains.get(target)!.has('existence'))
@@ -371,5 +393,6 @@ function applyPrepared(
   );
   const roots = [...retired].filter((node) => !node.parent || !retired.has(node.parent));
   if (roots.length) owner[destroySubtrees](roots);
+  for (const target of recreated) initializeNode(target.node);
   context.bounds.invalidate();
 }

package/src/changes/service.ts

@@ -16,6 +16,10 @@ interface ChangeAdapter {
   diff(target: NodeHandle, before: ModelSnapshot, after: ModelSnapshot): ModelChange[];
   immutable<Value>(value: Value): Value;
 }
+interface ChildOrder {
+  readonly nodes: readonly AnyNode[];
+  readonly indices: ReadonlyMap<AnyNode, number>;
+}
 
 export class ChangeService {
   private readonly listeners = new Set<(event: ChangeEvent) => void>();
@@ -41,10 +45,8 @@ export class ChangeService {
   }[] = [];
   private adapter?: ChangeAdapter;
   private validationCounts?: ReadonlyMap<AnyNode, number>;
-  private childOrders = new Map<
-    AnyNode,
-    { nodes: readonly AnyNode[]; indices: ReadonlyMap<AnyNode, number> }
-  >();
+  private childOrders = new Map<AnyNode, ChildOrder>();
+  private liveOrders = new WeakMap<AnyNode, ChildOrder>();
 
   constructor(private readonly context: DrawingContext) {}
 
@@ -54,13 +56,21 @@ export class ChangeService {
   get replaying(): boolean {
     return this.replayDepth > 0;
   }
+  /** The surrounding synchronous edit, if one is already grouping model writes. */
+  get currentGroup(): number | undefined {
+    return this.metadata.group;
+  }
 
   children(node: AnyNode): readonly AnyNode[] | undefined {
     if (!('children' in node)) return undefined;
     let order = this.childOrders.get(node);
     if (!order) {
-      const nodes = [...(node as AnyNode & { children: readonly AnyNode[] }).children];
-      order = { nodes, indices: new Map(nodes.map((child, index) => [child, index])) };
+      order = this.liveOrders.get(node);
+      if (!order) {
+        const nodes = [...(node as AnyNode & { children: readonly AnyNode[] }).children];
+        order = { nodes, indices: new Map(nodes.map((child, index) => [child, index])) };
+        this.liveOrders.set(node, order);
+      }
       this.childOrders.set(node, order);
     }
     return order.nodes;
@@ -75,6 +85,10 @@ export class ChangeService {
   resetOrders(): void {
     this.childOrders = new Map();
   }
+  /** Keep the operation's original order, but invalidate the live order after a tree edit. */
+  invalidateOrder(node: AnyNode): void {
+    this.liveOrders.delete(node);
+  }
 
   reading<Result>(callback: () => Result): Result {
     const previous = this.capturing;
@@ -418,5 +432,6 @@ export class ChangeService {
     this.groups.clear();
     this.owner = null;
     this.childOrders.clear();
+    this.liveOrders = new WeakMap();
   }
 }

package/src/components/changes.ts

@@ -0,0 +1,131 @@
+import type { AnyNode } from '../core/types.js';
+import type { DrawingContext } from '../services/context.js';
+import { deriveChanges, observeChanges, withChanges, type ChangeBatch } from '../changes.js';
+
+export interface Binding {
+  readonly node: AnyNode;
+  derive(): void;
+  replay(): void;
+  paint(): void;
+}
+interface Discovery {
+  added(node: AnyNode): void;
+  identityChanged(node: AnyNode): void;
+}
+const drawings = new WeakMap<DrawingContext, ComponentChanges>();
+
+/** Routes work by changed node, independent of the number of components in a drawing. */
+export class ComponentChanges {
+  private readonly bindings = new WeakMap<AnyNode, Binding>();
+  private readonly discovery = new Set<Discovery>();
+  private bindingCount = 0;
+  private readonly dirty = new Set<Binding>();
+  private cancelFrame?: () => void;
+  private readonly stopDerive: () => void;
+  private readonly stopObserve: () => void;
+  private readonly context: DrawingContext;
+
+  static for(node: AnyNode): ComponentChanges {
+    let changes = drawings.get(node.context);
+    if (!changes) {
+      changes = new ComponentChanges(node);
+      drawings.set(node.context, changes);
+    }
+    return changes;
+  }
+
+  private constructor(drawing: AnyNode) {
+    this.context = drawing.context;
+    this.stopDerive = deriveChanges(drawing, ({ nodes }) => {
+      for (const node of nodes) this.bindings.get(node)?.derive();
+    });
+    this.stopObserve = observeChanges(drawing, (event) => {
+      if (event.type === 'change') this.dispatch(event);
+    });
+  }
+
+  bind(binding: Binding): () => void {
+    if (this.bindings.has(binding.node)) throw new Error('Component is already observing changes');
+    this.bindings.set(binding.node, binding);
+    this.bindingCount++;
+    return this.release(() => {
+      this.bindings.delete(binding.node);
+      this.dirty.delete(binding);
+      this.bindingCount--;
+    });
+  }
+
+  discover(discovery: Discovery): () => void {
+    this.discovery.add(discovery);
+    return this.release(() => this.discovery.delete(discovery));
+  }
+
+  private release(cleanup: () => void): () => void {
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      cleanup();
+      if (!this.bindingCount && !this.discovery.size) {
+        this.cancelFrame?.();
+        this.stopDerive();
+        this.stopObserve();
+        drawings.delete(this.context);
+      }
+    };
+  }
+
+  /** Live state from every instance renders in one shared frame, as one temporary change. */
+  schedule(binding: Binding): void {
+    this.dirty.add(binding);
+    this.cancelFrame ??= this.context.dom.requestFrame(() => {
+      this.cancelFrame = undefined;
+      this.paint(this.dirty);
+    });
+  }
+
+  /** Renders without an undo step; failures surface after every other instance rendered. */
+  paint(bindings: Iterable<Binding>): void {
+    const list = [...bindings].filter((binding) => !binding.node.isDestroyed);
+    for (const binding of list) this.dirty.delete(binding);
+    if (!list.length) return;
+    const failures: unknown[] = [];
+    withChanges(list[0].node, { source: 'components', temporary: true }, () => {
+      for (const binding of list)
+        try {
+          binding.paint();
+        } catch (error) {
+          failures.push(error);
+        }
+    });
+    if (failures.length > 1) throw new AggregateError(failures, 'Component renders failed');
+    if (failures.length) throw failures[0];
+  }
+
+  private dispatch(event: ChangeBatch): void {
+    // Replay skips rendered children, so restored and recreated instances redraw together.
+    const replayed = new Set<Binding>();
+    for (const change of event.changes) {
+      const node = change.target.node,
+        binding = this.bindings.get(node);
+      if (
+        binding &&
+        event.source === 'replay' &&
+        ((change.domain === 'property' && change.attribute === 'data-rasam-props') ||
+          (change.domain === 'existence' && change.after))
+      )
+        replayed.add(binding);
+      if (!this.discovery.size) continue;
+      if (
+        (change.domain === 'placement' && change.after.parent && !change.before.parent) ||
+        (change.domain === 'existence' && change.after)
+      )
+        for (const subscriber of this.discovery) subscriber.added(node);
+      else if (change.domain === 'property' && change.attribute === 'data-rasam-component')
+        for (const subscriber of this.discovery) subscriber.identityChanged(node);
+    }
+    if (!replayed.size) return;
+    for (const binding of replayed) binding.replay();
+    this.paint(replayed);
+  }
+}

package/src/components/component.ts

@@ -0,0 +1,401 @@
+import { Group } from '../elements/group.js';
+import type { DrawingContext } from '../services/context.js';
+import type { SvgTemplate } from '../template/svg-tag.js';
+import { beginChangeGroup } from '../changes.js';
+import { derivesChildren, markDerived } from '../changes/derived.js';
+import { initializeElement } from '../services/initialization.js';
+import { definition, isSize, validatePorts, validateProp } from './metadata.js';
+import { ComponentView } from './view.js';
+import { ComponentChanges } from './changes.js';
+import { Attributes } from '../dom/attributes.js';
+import type { AttributeValue, Length, PortDefinition } from '../types/common.js';
+import type { creationOptions } from '../services/types.js';
+import type {
+  ActionDefinition,
+  ComponentDefinition,
+  ComponentProps,
+  PropDefinition,
+  PropOptions,
+  PropValue,
+  ComponentFields,
+} from './types.js';
+
+export const installField = Symbol('installComponentField');
+export const assertField = Symbol('assertComponentField');
+export const editComponent = Symbol('editComponent');
+export const registerAction = Symbol('registerComponentAction');
+const restoredHooks = new WeakSet<Component>();
+interface Field {
+  readonly kind: 'prop' | 'state';
+  readonly initial: unknown;
+  readonly options: PropOptions;
+  value: unknown;
+}
+const sizes = ['width', 'height'] as const;
+const copy = <Value>(value: Value): Value =>
+  value && typeof value === 'object' ? structuredClone(value) : value;
+
+/** A closed rasam group whose children are rendered from decorated props and live state. */
+export abstract class Component extends Group {
+  declare readonly [creationOptions]: ComponentFields<this>;
+  static override readonly ownsChildren = true;
+  /** @internal History restores props; the component redraws its children after replay. */
+  static readonly [derivesChildren] = true;
+  readonly #fields = new Map<string, Field>();
+  readonly #view = new ComponentView(this);
+  #initialized = false;
+  #constructing = true;
+  #schedule?: () => void;
+  #observedProps: ComponentProps = {};
+  #propsCache?: { raw: string | number | undefined; props: ComponentProps };
+  #propDefinitions?: readonly PropDefinition[];
+  readonly #actions = new Map<string, string>();
+  #ports?: { props: ComponentProps; ports: readonly PortDefinition[] };
+  #readingPorts = false;
+
+  readonly #input: ComponentProps;
+  readonly #reserved: ReadonlySet<string>;
+
+  constructor(context: DrawingContext, input: ComponentProps = {}, existing?: SVGGElement) {
+    super(context, {}, existing);
+    this.#input = input;
+    this.#reserved = new Set(Object.getOwnPropertyNames(this));
+  }
+
+  get componentDefinition(): ComponentDefinition {
+    return definition(this.constructor);
+  }
+  get editRules() {
+    const { rotate, flip, resize } = this.componentDefinition;
+    return Object.freeze({ rotate, flip, resize });
+  }
+  get propDefinitions(): readonly PropDefinition[] {
+    return (this.#propDefinitions ??= Object.freeze(
+      [...this.#fields]
+        .filter(([, field]) => field.kind === 'prop')
+        .map(([name, field]) =>
+          Object.freeze({ ...field.options, name, initial: field.initial as PropValue }),
+        ),
+    ));
+  }
+
+  /** `@action` methods with their undo labels, in declaration order; overrides relabel. */
+  get actionDefinitions(): readonly ActionDefinition[] {
+    return Object.freeze([...this.#actions].map(([name, label]) => Object.freeze({ name, label })));
+  }
+
+  /** @internal The `@action` decorator records each method once per instance. */
+  [registerAction](name: string, label: string): void {
+    this.#actions.set(name, label);
+  }
+
+  render(): SvgTemplate {
+    throw new TypeError('Components must implement render()');
+  }
+
+  /**
+   * Override to declare connection points, in local coordinates at 0°, from props and
+   * the saved size. Live state never moves a port. Defaults to none.
+   */
+  ports(): readonly PortDefinition[] {
+    return [];
+  }
+
+  /** Validated, frozen `ports()`, computed again only when the saved props change. */
+  get portDefinitions(): readonly PortDefinition[] {
+    const props = this.#readProps();
+    if (this.#ports?.props === props) return this.#ports.ports;
+    this.#readingPorts = true;
+    try {
+      const ports = validatePorts(this.ports());
+      this.#ports = { props, ports };
+      return ports;
+    } finally {
+      this.#readingPorts = false;
+    }
+  }
+  created(): void {}
+  destroyed(): void {}
+  changed(_name: string): void {}
+
+  override validateAttribute(name: string, value: AttributeValue): void {
+    super.validateAttribute(name, value);
+    if (
+      Attributes.normalizeName(name) === 'data-rasam-props' &&
+      #initialized in this &&
+      this.#initialized
+    )
+      this.#assertProps(parseProps(value));
+  }
+
+  override setAttributeValue(name: string, value: AttributeValue): this {
+    if (restoredHooks.has(this) && Attributes.normalizeName(name) === 'data-rasam-props')
+      return this;
+    return super.setAttributeValue(name, value);
+  }
+
+  override attrs(values: Parameters<Group['attrs']>[0]): this {
+    if (restoredHooks.has(this))
+      values = Object.fromEntries(
+        Object.entries(values).filter(
+          ([name]) => Attributes.normalizeName(name) !== 'data-rasam-props',
+        ),
+      );
+    return super.attrs(values);
+  }
+
+  /** `resize: 'props'` components keep their size as saved `width` and `height` props. */
+  get #sized(): boolean {
+    return this.componentDefinition.resize === 'props';
+  }
+
+  override width(): Length | null;
+  override width(value: Length): this;
+  override width(value?: Length): Length | null | this {
+    if (!this.#sized) return value === undefined ? super.width() : super.width(value);
+    return value === undefined ? this.#size('width') : this.size(value, this.#size('height'));
+  }
+  override height(): Length | null;
+  override height(value: Length): this;
+  override height(value?: Length): Length | null | this {
+    if (!this.#sized) return value === undefined ? super.height() : super.height(value);
+    return value === undefined ? this.#size('height') : this.size(this.#size('width'), value);
+  }
+
+  /** For `resize: 'props'`, one undo step that redraws at once, so callers read new bounds. */
+  override size(width: Length, height?: Length): this {
+    if (!this.#sized) return super.size(width, height);
+    this.assertLive();
+    const next = {
+      width: toSize(width),
+      height: height === undefined ? undefined : toSize(height),
+    };
+    const target = {
+      width: next.width,
+      height: next.height ?? (next.width * this.#size('height')) / this.#size('width'),
+    };
+    if (restoredHooks.has(this)) return this;
+    if (target.width === this.#size('width') && target.height === this.#size('height')) return this;
+    this[editComponent](`Resize ${this.componentDefinition.name}`, () => {
+      this.setAttributeValue(
+        'data-rasam-props',
+        JSON.stringify({ ...this.#readProps(), ...target }),
+      );
+    });
+    if (this.#initialized && this.#notifyProps()) this.#redraw();
+    return this;
+  }
+
+  #size(name: (typeof sizes)[number]): number {
+    const saved = this.#readProps()[name] ?? this.#input[name];
+    return isSize(saved) ? saved : this.componentDefinition[name]!;
+  }
+
+  resetState(): void {
+    this.assertLive();
+    for (const [name, field] of this.#fields)
+      if (field.kind === 'state') Reflect.set(this, name, copy(field.initial));
+  }
+
+  /** @internal Called after decorated fields and reconstructed children are available. */
+  [initializeElement](): void {
+    if (this.#initialized) return;
+    const metadata = this.componentDefinition;
+    const saved = this.#readProps();
+    const rawVersion = this.getAttributeValue('data-rasam-version');
+    const version = rawVersion === undefined ? metadata.version : Number(rawVersion);
+    if (!Number.isInteger(version) || version < 1 || version > metadata.version)
+      throw new TypeError(`Unsupported ${metadata.type} component version: ${rawVersion}`);
+    if (version < metadata.version && !metadata.migrate)
+      throw new TypeError(`No migration for ${metadata.type} version ${version}`);
+    const values = version < metadata.version ? metadata.migrate!(saved, version) : saved;
+    this.#assertProps(values);
+    this.#assertProps(this.#input);
+    const props: Record<string, PropValue> = {};
+    for (const [name, field] of this.#fields)
+      if (field.kind === 'prop') {
+        const value = Object.hasOwn(this.#input, name)
+          ? this.#input[name]
+          : Object.hasOwn(values, name)
+            ? values[name]
+            : field.initial;
+        validateProp(value, field.initial as PropValue, field.options, name);
+        props[name] = value;
+      }
+    if (metadata.resize === 'props')
+      for (const name of sizes)
+        props[name] = (this.#input[name] ?? values[name] ?? metadata[name]) as number;
+    this.#initialized = true;
+    if (!this.context.changes.replaying) {
+      this.setAttributeValue('data-rasam-version', metadata.version);
+      this.setAttributeValue('data-rasam-props', JSON.stringify(props));
+      this.#redraw();
+    }
+    this.#observedProps = this.#readProps();
+    const changes = ComponentChanges.for(this);
+    const binding = {
+      node: this,
+      derive: () => {
+        if (this.#notifyProps()) this.#redraw();
+      },
+      replay: () => {
+        this.#notifyProps();
+      },
+      paint: () => this.#redraw(),
+    };
+    const stop = changes.bind(binding);
+    this.#schedule = () => changes.schedule(binding);
+    this.onDispose(() => {
+      stop();
+      this.destroyed();
+    });
+    this.context.changes.local(() => {
+      if (this.adopting) restoredHooks.add(this);
+      try {
+        this.created();
+      } finally {
+        restoredHooks.delete(this);
+        this.#constructing = false;
+      }
+      // A newly constructed, detached node is not eligible for change derivation yet.
+      if (this.#readProps() !== this.#observedProps && this.#notifyProps()) this.#redraw();
+    });
+  }
+
+  /** @internal Field decorators install accessors after their initializers execute. */
+  [assertField](name: string): void {
+    if (name in Component.prototype || this.#fields.has(name) || this.#reserved.has(name))
+      throw new TypeError(`Component field conflicts with an inherited rasam member: ${name}`);
+  }
+
+  /** @internal Field decorators install accessors after their initializers execute. */
+  [installField](
+    name: string,
+    kind: 'prop' | 'state',
+    options: PropOptions,
+    initial: unknown,
+  ): void {
+    this[assertField](name);
+    if (kind === 'prop') validateProp(initial, initial as PropValue, options, name);
+    const field: Field = {
+      kind,
+      options: Object.freeze({
+        ...options,
+        ...(options.options ? { options: Object.freeze([...options.options]) } : {}),
+      }),
+      initial: copy(initial),
+      value: initial,
+    };
+    this.#fields.set(name, field);
+    this.#propDefinitions = undefined;
+    Object.defineProperty(this, name, {
+      enumerable: true,
+      configurable: false,
+      get: () => {
+        if (kind === 'state') {
+          if (this.#readingPorts) throw new TypeError(`ports() cannot read live state: ${name}`);
+          return field.value;
+        }
+        const props = this.#readProps();
+        return Object.hasOwn(props, name)
+          ? props[name]
+          : Object.hasOwn(this.#input, name)
+            ? this.#input[name]
+            : initial;
+      },
+      set: (value: unknown) => {
+        this.assertLive();
+        if (kind === 'state') {
+          if (Object.is(field.value, value)) return;
+          field.value = value;
+          if (this.#initialized) {
+            this.changed(name);
+            this.#schedule?.();
+          }
+          return;
+        }
+        if (restoredHooks.has(this)) return;
+        validateProp(value, initial as PropValue, options, name);
+        if (Object.is(Reflect.get(this, name), value)) return;
+        this[editComponent](`Set ${options.label ?? name}`, () => {
+          this.setAttributeValue(
+            'data-rasam-props',
+            JSON.stringify({ ...this.#readProps(), [name]: value }),
+          );
+        });
+      },
+    });
+  }
+
+  /** @internal Actions share one change group across nested calls and instances. */
+  [editComponent]<Result>(label: string, callback: () => Result): Result {
+    this.assertLive();
+    if (this.#constructing || this.context.changes.currentGroup !== undefined) return callback();
+    const group = beginChangeGroup(this, { source: 'components', label });
+    try {
+      const result = group.run(callback);
+      if (result && typeof (result as PromiseLike<unknown>).then === 'function')
+        throw new TypeError('Component actions must be synchronous');
+      group.end();
+      return result;
+    } catch (error) {
+      try {
+        group.cancel();
+      } catch (rollback) {
+        throw new AggregateError([error, rollback], 'Component edit and rollback failed');
+      }
+      throw error;
+    }
+  }
+
+  #readProps(): ComponentProps {
+    // Retain ordinary field-read semantics for destroyed() and post-disposal inspection.
+    const raw = this.attributes.get('data-rasam-props');
+    if (this.#propsCache && this.#propsCache.raw === raw) return this.#propsCache.props;
+    this.#propsCache = { raw, props: Object.freeze(parseProps(raw)) };
+    return this.#propsCache.props;
+  }
+  #assertProps(props: ComponentProps): void {
+    if (!props || typeof props !== 'object' || Array.isArray(props))
+      throw new TypeError('Component props must be an object');
+    for (const [name, value] of Object.entries(props)) {
+      if (this.#sized && (sizes as readonly string[]).includes(name)) {
+        if (!isSize(value)) throw new RangeError(`Component ${name} must be a positive number`);
+        continue;
+      }
+      const field = this.#fields.get(name);
+      if (!field || field.kind !== 'prop') throw new TypeError(`Unknown component prop: ${name}`);
+      validateProp(value, field.initial as PropValue, field.options, name);
+    }
+  }
+  #notifyProps(): boolean {
+    const props = this.#readProps(),
+      previous = this.#observedProps;
+    if (props === previous) return false;
+    this.#observedProps = props;
+    const names = [...this.propDefinitions.map((field) => field.name), ...sizes].filter(
+      (name) => !Object.is(previous[name], props[name]),
+    );
+    for (const name of names) this.changed(name);
+    return names.length > 0;
+  }
+  #redraw(): void {
+    this.withOwnChildren(() => this.#view.render(this.render()));
+    markDerived(this);
+  }
+}
+
+/** Sizes are user units of at least 1, so a collapsing resize never reaches zero. */
+function toSize(value: Length): number {
+  const size = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(size) || size < 0)
+    throw new RangeError('Component sizes must be finite non-negative numbers');
+  return Math.max(size, 1);
+}
+
+function parseProps(raw: AttributeValue): ComponentProps {
+  const props: unknown = raw == null ? {} : JSON.parse(String(raw));
+  if (!props || typeof props !== 'object' || Array.isArray(props))
+    throw new TypeError('Component props must be a JSON object');
+  return props as ComponentProps;
+}