@textui/core 0.1.0

package/src/core/layers.ts

@@ -0,0 +1,94 @@
+import type { LayerEntry, LayerManager, LayerName } from '../types/layer.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable } from '../util/disposable.js';
+
+const LAYER_ORDER: LayerName[] = ['base', 'floating', 'modal', 'notification', 'debug'];
+
+/**
+ * Layers are planes, not components.
+ *
+ * Dialogs, dropdowns, context menus, tooltips, palettes and toasts all sit on
+ * one of five, which is what lets focus trapping, dismissal and paint order be
+ * decided once here rather than five times in five components.
+ */
+export class Layers implements LayerManager {
+  private byId = new Map<string, LayerEntry>();
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private counter = 0;
+
+  constructor(private onChange: () => void = () => {}) {}
+
+  open(entry: LayerEntry): Disposable {
+    const order = entry.order ?? ++this.counter;
+    this.byId.set(entry.id, { ...entry, order });
+
+    if (entry.timeoutMs && entry.timeoutMs > 0) {
+      const timer = setTimeout(() => this.close(entry.id, 'timeout'), entry.timeoutMs);
+      timer.unref?.();
+      this.timers.set(entry.id, timer);
+    }
+
+    this.onChange();
+    return toDisposable(() => this.close(entry.id, 'api'));
+  }
+
+  close(id: string, reason: 'escape' | 'outside' | 'timeout' | 'api' = 'api'): void {
+    const entry = this.byId.get(id);
+    if (!entry) return;
+
+    const timer = this.timers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(id);
+    }
+
+    this.byId.delete(id);
+    try {
+      entry.onClose?.(reason);
+    } finally {
+      this.onChange();
+    }
+  }
+
+  closeLayer(layer: LayerName): void {
+    for (const entry of this.entries(layer)) this.close(entry.id, 'api');
+  }
+
+  /** Sorted by plane, then by open order - which is paint order. */
+  entries(layer?: LayerName): LayerEntry[] {
+    const all = [...this.byId.values()];
+    const filtered = layer ? all.filter((e) => e.layer === layer) : all;
+    return filtered.sort((a, b) => {
+      const byLayer = LAYER_ORDER.indexOf(a.layer) - LAYER_ORDER.indexOf(b.layer);
+      return byLayer !== 0 ? byLayer : (a.order ?? 0) - (b.order ?? 0);
+    });
+  }
+
+  topmostTrap(): LayerEntry | null {
+    const trapping = this.entries().filter((e) => e.trapFocus);
+    return trapping[trapping.length - 1] ?? null;
+  }
+
+  /** The entry Escape should close: the last dismissible one. */
+  topmostDismissible(): LayerEntry | null {
+    const list = this.entries().filter((e) => e.dismissOnEscape !== false);
+    return list[list.length - 1] ?? null;
+  }
+
+  update(id: string, patch: Partial<LayerEntry>): void {
+    const entry = this.byId.get(id);
+    if (!entry) return;
+    this.byId.set(id, { ...entry, ...patch });
+    this.onChange();
+  }
+
+  dispose(): void {
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+    this.byId.clear();
+  }
+}
+
+export function createLayers(onChange?: () => void): Layers {
+  return new Layers(onChange);
+}

package/src/core/manifest.ts

@@ -0,0 +1,84 @@
+import type { Manifest, ManifestAPI, ManifestSource } from '../types/manifest.js';
+import type { TextUIApp } from '../types/app.js';
+import type { Disposable } from '../types/disposable.js';
+import { createBag } from '../util/disposable.js';
+
+/**
+ * Manifests.
+ *
+ * Separate typed lists rather than one generic plugin bag: every category has
+ * its own contract, so a bad contribution fails where it is written instead of
+ * at some later lookup. Loading returns one disposable that unwinds everything
+ * the source contributed, which is what makes unloading exact.
+ */
+export class Manifests implements ManifestAPI {
+  private loaded_ = new Map<string, { source: ManifestSource; disposable: Disposable }>();
+
+  constructor(private app: TextUIApp) {}
+
+  async load(manifest: Manifest): Promise<Disposable> {
+    const { id } = manifest.source;
+    if (this.loaded_.has(id)) {
+      throw new Error(`[textui] manifest "${id}" is already loaded`);
+    }
+
+    for (const required of manifest.requires ?? []) {
+      if (!this.loaded_.has(required)) {
+        throw new Error(`[textui] manifest "${id}" requires "${required}", which is not loaded`);
+      }
+    }
+
+    const caps = this.app.capabilities as unknown as Record<string, unknown>;
+    const missing = (manifest.requiresCapabilities ?? []).filter((c) => !caps[c]);
+    if (missing.length > 0) {
+      throw new Error(
+        `[textui] manifest "${id}" needs terminal capabilities this session lacks: ${missing.join(', ')}`,
+      );
+    }
+
+    const bag = createBag();
+    const c = manifest.contributes ?? {};
+
+    for (const def of c.components ?? []) bag.add(this.app.components.register(def));
+    for (const def of c.commands ?? []) bag.add(this.app.commands.register(def));
+    for (const def of c.keybindings ?? []) bag.add(this.app.keybindings.register(def));
+    for (const def of c.themes ?? []) bag.add(this.app.themes.register(def));
+    for (const def of c.shells ?? []) bag.add(this.app.shells.register(def));
+    for (const def of c.layouts ?? []) bag.add(this.app.layouts.register(def));
+    for (const def of c.screens ?? []) bag.add(this.app.screens.register(def));
+    for (const def of c.resourceKinds ?? []) bag.add(this.app.resources.registerKind(def));
+    for (const def of c.resourceProviders ?? []) bag.add(this.app.resources.registerProvider(def));
+    for (const def of c.resourceViewers ?? []) bag.add(this.app.resources.registerViewer(def));
+    for (const def of c.resourceEditors ?? []) bag.add(this.app.resources.registerEditor(def));
+    for (const def of c.resourceActions ?? []) bag.add(this.app.resources.registerAction(def));
+    for (const def of c.dataProviders ?? []) bag.add(this.app.store.registerDataProvider(def));
+    for (const entry of c.computed ?? []) bag.add(this.app.store.computed(entry.path, entry.def));
+    // Views mount last: they may name a component this manifest just added.
+    for (const mount of c.views ?? []) bag.add(this.app.open(mount));
+
+    const disposable = {
+      dispose: () => {
+        bag.dispose();
+        this.loaded_.delete(id);
+      },
+    };
+    this.loaded_.set(id, { source: manifest.source, disposable });
+    return disposable;
+  }
+
+  unload(sourceId: string): void {
+    this.loaded_.get(sourceId)?.disposable.dispose();
+  }
+
+  sources(): ManifestSource[] {
+    return [...this.loaded_.values()].map((e) => e.source);
+  }
+
+  loaded(sourceId: string): boolean {
+    return this.loaded_.has(sourceId);
+  }
+}
+
+export function createManifests(app: TextUIApp): Manifests {
+  return new Manifests(app);
+}

package/src/core/navigation.ts

@@ -0,0 +1,135 @@
+import type { Navigator, ScreenDefinition, ScreenEntry } from '../types/navigation.js';
+import type { ReactiveStore } from '../types/store.js';
+import type { FocusManager } from '../types/focus.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable } from '../util/disposable.js';
+
+/**
+ * Screens and a stack, not a router.
+ *
+ * The whole navigation model is "what is on top", plus enough memory to put
+ * focus back where it was when you return. An application that wants URLs maps
+ * them onto screens itself; nothing here assumes a browser exists.
+ */
+export class Navigation implements Navigator {
+  private defs = new Map<string, ScreenDefinition>();
+  private entries: ScreenEntry[] = [];
+
+  constructor(
+    private deps: {
+      store: ReactiveStore;
+      focus: FocusManager;
+      onChange(): void;
+      /**
+       * Put the current screen on screen.
+       *
+       * A callback rather than a surface registry, because what a screen *is*
+       * - a stack entry and a definition - has nothing to do with where the
+       * application decided to draw it.
+       */
+      mount(entry: ScreenEntry | null): void;
+    },
+  ) {}
+
+  register(screen: ScreenDefinition): Disposable {
+    this.defs.set(screen.id, screen);
+    return toDisposable(() => this.defs.delete(screen.id));
+  }
+
+  screens(): ScreenDefinition[] {
+    return [...this.defs.values()];
+  }
+
+  get(id: string): ScreenDefinition | undefined {
+    return this.defs.get(id);
+  }
+
+  private publish(): void {
+    const current = this.current();
+    this.deps.store.set('$/layout/screen/stack', this.entries.map((e) => e.id));
+    this.deps.store.set('$/layout/screen/current', current?.id ?? null);
+    // Published as well as passed as props, so a component deep inside a
+    // screen can read the parameters without every layer between forwarding
+    // them.
+    this.deps.store.set('$/layout/screen/params', current?.params ?? {});
+    this.deps.mount(current);
+    this.deps.onChange();
+  }
+
+  /** Remember where focus was, so `pop` can put it back. */
+  private snapshotFocus(): void {
+    const top = this.entries[this.entries.length - 1];
+    if (top) top.restoreFocus = this.deps.focus.focused();
+  }
+
+  push(id: string, params?: Record<string, unknown>): void {
+    if (!this.defs.has(id)) {
+      throw new Error(`[textui] no screen registered as "${id}"`);
+    }
+    this.snapshotFocus();
+    this.entries.push({ id, params });
+    this.publish();
+  }
+
+  replace(id: string, params?: Record<string, unknown>): void {
+    if (!this.defs.has(id)) {
+      throw new Error(`[textui] no screen registered as "${id}"`);
+    }
+    const previous = this.entries.pop();
+    this.clearScreenScope(previous);
+    this.entries.push({ id, params });
+    this.publish();
+  }
+
+  pop(): boolean {
+    if (this.entries.length <= 1) return false;
+    const previous = this.entries.pop();
+    this.clearScreenScope(previous);
+
+    const top = this.entries[this.entries.length - 1];
+    if (top?.restoreFocus) this.deps.focus.focus(top.restoreFocus);
+    this.publish();
+    return true;
+  }
+
+  popTo(id: string): boolean {
+    const index = this.entries.findIndex((e) => e.id === id);
+    if (index === -1) return false;
+    for (const entry of this.entries.slice(index + 1)) this.clearScreenScope(entry);
+    this.entries = this.entries.slice(0, index + 1);
+
+    const top = this.entries[this.entries.length - 1];
+    if (top?.restoreFocus) this.deps.focus.focus(top.restoreFocus);
+    this.publish();
+    return true;
+  }
+
+  reset(id: string, params?: Record<string, unknown>): void {
+    for (const entry of this.entries) this.clearScreenScope(entry);
+    this.entries = [{ id, params }];
+    this.publish();
+  }
+
+  current(): ScreenEntry | null {
+    return this.entries[this.entries.length - 1] ?? null;
+  }
+
+  stack(): ScreenEntry[] {
+    return [...this.entries];
+  }
+
+  canGoBack(): boolean {
+    return this.entries.length > 1;
+  }
+
+  /** A screen's own scope dies with it, unless it asked to be kept alive. */
+  private clearScreenScope(entry: ScreenEntry | undefined): void {
+    if (!entry) return;
+    if (this.defs.get(entry.id)?.keepAlive) return;
+    this.deps.store.clearScope(`screen.${entry.id}`);
+  }
+}
+
+export function createNavigation(deps: ConstructorParameters<typeof Navigation>[0]): Navigation {
+  return new Navigation(deps);
+}

package/src/core/resources.ts

@@ -0,0 +1,362 @@
+import type {
+  Resource, ResourceActionDefinition, ResourceEditorDefinition, ResourceKind,
+  ResourceMetadata, ResourceProvider, ResourceRegistry, ResourceURI,
+  ResourceRendererDefinition, ResourceViewerDefinition,
+} from '../types/resource.js';
+import type { ComponentNode } from '../types/graph.js';
+import type { ComponentRegistry } from '../types/component-registry.js';
+import type { WhenEngine } from '../types/when.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable } from '../util/disposable.js';
+import { nameOf } from './syntax.js';
+import type { SemanticVariant } from '../types/style.js';
+
+function schemeOf(uri: ResourceURI): string {
+  const i = uri.indexOf(':');
+  return i === -1 ? 'file' : uri.slice(0, i);
+}
+
+function matchesGlob(name: string, pattern: string): boolean {
+  if (pattern.startsWith('*.')) return name.toLowerCase().endsWith(pattern.slice(1).toLowerCase());
+  return name.toLowerCase() === pattern.toLowerCase();
+}
+
+/**
+ * The resource model.
+ *
+ * A resource is anything addressable that something can be registered to
+ * display, edit or act on - a file, a record, a log stream, a service. The
+ * filesystem is one provider among several rather than the model itself, which
+ * is what lets an explorer browse services and files with the same component.
+ *
+ * Kinds form a hierarchy by dotted name: `file.markdown` specialises
+ * `file.text`, so a viewer registered for `file.text` still opens a markdown
+ * file when no more specific one exists.
+ */
+export class Resources implements ResourceRegistry {
+  private kindDefs = new Map<string, ResourceKind>();
+  private providers = new Map<string, ResourceProvider>();
+  private viewers: ResourceViewerDefinition[] = [];
+  private editors: ResourceEditorDefinition[] = [];
+  private actions: ResourceActionDefinition[] = [];
+
+  constructor(
+    private deps: {
+      components: ComponentRegistry;
+      when: WhenEngine;
+    },
+  ) {}
+
+  registerKind(kind: ResourceKind): Disposable {
+    this.kindDefs.set(kind.id, kind);
+    return toDisposable(() => this.kindDefs.delete(kind.id));
+  }
+
+  registerProvider(provider: ResourceProvider): Disposable {
+    this.providers.set(provider.scheme, provider);
+    return toDisposable(() => this.providers.delete(provider.scheme));
+  }
+
+  registerViewer(def: ResourceViewerDefinition): Disposable {
+    this.viewers.push(def);
+    return toDisposable(() => {
+      const i = this.viewers.indexOf(def);
+      if (i >= 0) this.viewers.splice(i, 1);
+    });
+  }
+
+  registerEditor(def: ResourceEditorDefinition): Disposable {
+    this.editors.push(def);
+    return toDisposable(() => {
+      const i = this.editors.indexOf(def);
+      if (i >= 0) this.editors.splice(i, 1);
+    });
+  }
+
+  registerAction(def: ResourceActionDefinition): Disposable {
+    this.actions.push(def);
+    return toDisposable(() => {
+      const i = this.actions.indexOf(def);
+      if (i >= 0) this.actions.splice(i, 1);
+    });
+  }
+
+  kinds(): ResourceKind[] {
+    return [...this.kindDefs.values()];
+  }
+
+  /** Extension, then mime type, then an explicit `detect`. Best match wins. */
+  detectKind(uri: ResourceURI, meta: ResourceMetadata = { name: uri }): string {
+    const name = meta.name || nameOf(uri) || uri;
+    const candidates: { id: string; score: number }[] = [];
+
+    for (const kind of this.kindDefs.values()) {
+      let score = kind.priority ?? 0;
+      let matched = false;
+
+      if (kind.extensions?.some((p) => matchesGlob(name, p))) {
+        score += 100;
+        matched = true;
+      }
+      if (meta.mimeType && kind.mimeTypes?.includes(meta.mimeType)) {
+        score += 80;
+        matched = true;
+      }
+      if (kind.detect?.(uri, meta)) {
+        score += 200;
+        matched = true;
+      }
+      // A more specific kind beats its parent on equal evidence.
+      if (matched) {
+        score += kind.id.split('.').length;
+        candidates.push({ id: kind.id, score });
+      }
+    }
+
+    if (candidates.length === 0) return meta.mimeType ? 'file' : 'unknown';
+    candidates.sort((a, b) => b.score - a.score);
+    return (candidates[0] as { id: string }).id;
+  }
+
+  kindMatches(kind: string, ancestor: string): boolean {
+    if (kind === ancestor) return true;
+    if (kind.startsWith(ancestor + '.')) return true;
+
+    let cursor = this.kindDefs.get(kind);
+    const seen = new Set<string>();
+    while (cursor?.extends && !seen.has(cursor.id)) {
+      seen.add(cursor.id);
+      if (cursor.extends === ancestor) return true;
+      cursor = this.kindDefs.get(cursor.extends);
+    }
+    return false;
+  }
+
+  private provider(uri: ResourceURI): ResourceProvider {
+    const scheme = schemeOf(uri);
+    const provider = this.providers.get(scheme);
+    if (!provider) {
+      throw new Error(`[textui] no resource provider registered for "${scheme}:"`);
+    }
+    return provider;
+  }
+
+  async stat(uri: ResourceURI): Promise<Resource | null> {
+    const resource = await this.provider(uri).stat(uri);
+    if (!resource) return null;
+    // A provider may leave classification to the registry.
+    if (!resource.kind || resource.kind === 'unknown') {
+      return { ...resource, kind: this.detectKind(uri, resource.metadata) };
+    }
+    return resource;
+  }
+
+  async list(uri: ResourceURI): Promise<Resource[]> {
+    const provider = this.provider(uri);
+    if (!provider.list) return [];
+    const items = await provider.list(uri);
+    return items.map((r) =>
+      r.kind && r.kind !== 'unknown' ? r : { ...r, kind: this.detectKind(r.uri, r.metadata) },
+    );
+  }
+
+  async read(uri: ResourceURI): Promise<string | Uint8Array> {
+    const provider = this.provider(uri);
+    if (!provider.read) throw new Error(`[textui] "${schemeOf(uri)}:" cannot be read`);
+    return provider.read(uri);
+  }
+
+  async write(uri: ResourceURI, content: string | Uint8Array): Promise<void> {
+    const provider = this.provider(uri);
+    if (!provider.write) throw new Error(`[textui] "${schemeOf(uri)}:" is read-only`);
+    return provider.write(uri, content);
+  }
+
+  /**
+   * Destructive calls throw when the provider cannot serve them, the same way
+   * `write` does. A silent no-op is the failure mode worth designing against:
+   * a Delete that appears in the menu and removes nothing is worse than one
+   * that says it cannot.
+   *
+   * Whether to *offer* the action is a different question, answered before
+   * the call by `Resource.capabilities` - which is per resource rather than
+   * per provider, so a read-only mount, a file without permission and an
+   * inherently immutable resource are all the same shape. The throw is for
+   * the race that asking first cannot close: the remote goes away, the
+   * permission changes, between the offer and the call.
+   */
+  async delete(uri: ResourceURI): Promise<void> {
+    const provider = this.provider(uri);
+    if (!provider.delete) throw new Error(`[textui] "${schemeOf(uri)}:" cannot delete`);
+    return provider.delete(uri);
+  }
+
+  /**
+   * A rename is within one provider. Two schemes is a move between providers,
+   * which is a copy and a delete and belongs above a registry that dispatches
+   * on a single scheme by construction.
+   */
+  async rename(from: ResourceURI, to: ResourceURI): Promise<void> {
+    const scheme = schemeOf(from);
+    if (schemeOf(to) !== scheme) {
+      throw new Error(
+        `[textui] cannot rename across schemes: "${scheme}:" to "${schemeOf(to)}:"`,
+      );
+    }
+    const provider = this.provider(from);
+    if (!provider.rename) throw new Error(`[textui] "${scheme}:" cannot rename`);
+    return provider.rename(from, to);
+  }
+
+  /**
+   * Watching follows `list` rather than `write`: a provider that cannot watch
+   * gets a disposable that does nothing, because "I will never tell you about
+   * a change" is a truthful answer to an optional question. Making every
+   * caller guard a subscription would buy nothing.
+   */
+  watch(uri: ResourceURI, fn: (event: 'change' | 'create' | 'delete') => void): Disposable {
+    const provider = this.provider(uri);
+    return provider.watch?.(uri, fn) ?? toDisposable(() => {});
+  }
+
+  viewersFor(kind: string): ResourceViewerDefinition[] {
+    const specific = this.viewers
+      .filter((v) => !v.fallback && v.kinds.some((k) => this.kindMatches(kind, k)))
+      .filter((v) => this.deps.when.evaluate(v.when))
+      .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+
+    const fallbacks = this.viewers
+      .filter((v) => v.fallback)
+      .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+
+    return [...specific, ...fallbacks];
+  }
+
+  editorsFor(kind: string): ResourceEditorDefinition[] {
+    return this.editors
+      .filter((e) => e.kinds.some((k) => this.kindMatches(kind, k)))
+      .filter((e) => this.deps.when.evaluate(e.when))
+      .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }
+
+  /**
+   * Every way of showing this kind, best first.
+   *
+   * Three registries answer the same question - an editor, a viewer and a
+   * component that declared `opens` are all "a component that can put this on
+   * screen" - and a panel offering "open with" wants one list. Saving is a
+   * property of the renderer here rather than the registry it came from, which
+   * is what lets `file.markdown` list an editor, a rendered view and plain
+   * text together and lets the panel pick between them.
+   */
+  /**
+   * What a resource looks like in a list.
+   *
+   * Asked of the *renderer* first, because the thing that knows what a
+   * markdown file is is the thing that opens markdown files - so a viewer an
+   * extension brought names and colours its own kind without anything here
+   * learning what it is. Then the kind, walking up `extends`, since
+   * `file.markdown` inheriting Text's icon is better than inheriting nothing.
+   *
+   * Answers nothing rather than a default: what a nameless file looks like is
+   * the caller's vocabulary, because which glyphs a terminal can draw is known
+   * where the terminal is and not here.
+   */
+  appearanceOf(resource: { kind: string }): { icon?: string; tone?: SemanticVariant } {
+    for (const renderer of this.renderersFor(resource.kind)) {
+      if (renderer.icon !== undefined || renderer.tone !== undefined) {
+        return {
+          ...(renderer.icon !== undefined ? { icon: renderer.icon } : {}),
+          ...(renderer.tone !== undefined ? { tone: renderer.tone } : {}),
+        };
+      }
+    }
+
+    const byId = new Map(this.kinds().map((k) => [k.id, k]));
+    // Bounded by the number of kinds: a cycle in `extends` is a bad
+    // registration and must not be an infinite loop in a list row.
+    const seen = new Set<string>();
+    let kind = byId.get(resource.kind);
+    while (kind && !seen.has(kind.id)) {
+      seen.add(kind.id);
+      if (kind.icon !== undefined || kind.tone !== undefined) {
+        return {
+          ...(kind.icon !== undefined ? { icon: kind.icon } : {}),
+          ...(kind.tone !== undefined ? { tone: kind.tone } : {}),
+        };
+      }
+      kind = kind.extends === undefined ? undefined : byId.get(kind.extends);
+    }
+    return {};
+  }
+
+  renderersFor(kind: string): ResourceRendererDefinition[] {
+    const seen = new Set<string>();
+    const out: ResourceRendererDefinition[] = [];
+    const add = (def: ResourceRendererDefinition): void => {
+      if (seen.has(def.id)) return;
+      seen.add(def.id);
+      out.push(def);
+    };
+
+    for (const e of this.editorsFor(kind)) add({ ...e, saves: true });
+    for (const v of this.viewersFor(kind)) add({ ...v, saves: false });
+    for (const c of this.deps.components.findOpeners(kind)) {
+      add({
+        id: c.component,
+        title: c.opens?.title ?? c.component,
+        kinds: c.opens?.resourceKinds ?? [],
+        component: c.component,
+        ...(c.opens?.icon !== undefined ? { icon: c.opens.icon } : {}),
+        ...(c.opens?.priority !== undefined ? { priority: c.opens.priority } : {}),
+        saves: c.opens?.mode === 'edit',
+      });
+    }
+
+    return out.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }
+
+  actionsFor(kind: string, slot?: string): ResourceActionDefinition[] {
+    return this.actions
+      .filter((a) => a.kinds.some((k) => this.kindMatches(kind, k) || k === '*'))
+      .filter((a) => !slot || (a.slots ?? ['context']).includes(slot))
+      .filter((a) => this.deps.when.evaluate(a.when))
+      .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }
+
+  /**
+   * The node that displays this resource. An explicit `viewerId` wins; then a
+   * registered editor when edit was asked for; then the best viewer; then a
+   * component that declared `opens` for this kind; then nothing.
+   */
+  nodeFor(
+    resource: Resource,
+    options: { viewerId?: string; mode?: 'view' | 'edit' } = {},
+  ): ComponentNode | null {
+    const props = { resource, uri: resource.uri };
+
+    if (options.viewerId) {
+      const chosen =
+        this.viewers.find((v) => v.id === options.viewerId) ??
+        this.editors.find((e) => e.id === options.viewerId);
+      return chosen ? { component: chosen.component, ...props } : null;
+    }
+
+    if (options.mode === 'edit') {
+      const editor = this.editorsFor(resource.kind)[0];
+      if (editor) return { component: editor.component, ...props };
+    }
+
+    const viewer = this.viewersFor(resource.kind)[0];
+    if (viewer) return { component: viewer.component, ...props };
+
+    const opener = this.deps.components.findOpeners(resource.kind)[0];
+    if (opener) return { component: opener.component, ...props };
+
+    return null;
+  }
+}
+
+export function createResources(deps: ConstructorParameters<typeof Resources>[0]): Resources {
+  return new Resources(deps);
+}