@textui/core 0.1.0

package/dist/core/keybindings.js

@@ -0,0 +1,163 @@
+import { toDisposable } from '../util/disposable.js';
+/** `ctrl+shift+p` or a sequence: `ctrl+k ctrl+s`, `g g`. */
+function parseChord(chord) {
+    return chord.trim().split(/\s+/).map(normalizeStroke);
+}
+const MODIFIER = /^(ctrl|control|alt|option|shift|meta|cmd|super)\+/i;
+/**
+ * Split one stroke into its modifiers and its key.
+ *
+ * Modifiers are consumed off the front by name and whatever survives is the
+ * key, verbatim. Splitting on `+` cannot work here: `+` is the separator and
+ * a key, so `'+'.split('+')` loses the only thing it was asked about. Parsing
+ * forwards means `+` is `+`, and `ctrl++` is ctrl and `+`.
+ *
+ * One parser, exported, because a chord that the test harness presses and a
+ * chord that the registry stored have to agree - and two implementations of
+ * one grammar disagree eventually.
+ */
+export function splitStroke(stroke) {
+    const mods = [];
+    let rest = stroke.trim();
+    for (let match = MODIFIER.exec(rest); match !== null; match = MODIFIER.exec(rest)) {
+        const [whole, name = ''] = match;
+        mods.push(name.toLowerCase());
+        rest = rest.slice(whole.length);
+    }
+    return { mods, key: rest };
+}
+/** The canonical stroke a chord is filed under. `strokeOf` must agree with it. */
+export function normalizeStroke(stroke) {
+    const { mods: names, key } = splitStroke(stroke);
+    const mods = new Set();
+    for (const name of names) {
+        if (name === 'ctrl' || name === 'control')
+            mods.add('ctrl');
+        else if (name === 'alt' || name === 'option')
+            mods.add('alt');
+        else if (name === 'shift')
+            mods.add('shift');
+        else
+            mods.add('meta');
+    }
+    // Shift is not part of a stroke for a single character it *shifted*. A
+    // terminal reports a bare shift+p as the character `P`, and `strokeOf` reads
+    // it back that way, so `shift+p` would wait for a stroke no keypress makes.
+    //
+    // Held with another modifier it is the opposite. `ctrl+shift+p` cannot
+    // arrive as an uppercase letter, because a control code carries no case:
+    // a terminal speaking a keyboard protocol reports the *unshifted* key and a
+    // shift bit beside it. Dropping shift here filed `ctrl+shift+f` under
+    // `ctrl+f`, where it sat behind whichever binding registered first - so the
+    // workspace search had a documented key that ran the in-file search.
+    if ([...key].length === 1 && mods.size === 1 && mods.has('shift'))
+        mods.delete('shift');
+    const order = ['ctrl', 'alt', 'shift', 'meta'].filter((m) => mods.has(m));
+    return [...order, key.toLowerCase()].join('+');
+}
+export function strokeOf(event) {
+    const mods = [];
+    if (event.ctrl)
+        mods.push('ctrl');
+    if (event.alt)
+        mods.push('alt');
+    // Shift is implied by an uppercase character, so it is not named for a
+    // single character on its own. Beside another modifier nothing is implied -
+    // the name is the unshifted key - so there it has to be said. Must agree
+    // with `normalizeStroke`.
+    const modified = event.ctrl || event.alt || event.meta;
+    if (event.shift && (event.name.length > 1 || modified))
+        mods.push('shift');
+    if (event.meta)
+        mods.push('meta');
+    return [...mods, event.name.toLowerCase()].join('+');
+}
+/**
+ * Keybindings resolve to commands, never to handlers, so the same action is
+ * reachable from a chord, a menu row and the palette without three copies.
+ * A partially typed chord is remembered, which is what makes `ctrl+k ctrl+s`
+ * possible without blocking `ctrl+k` on its own.
+ */
+export class Keybindings {
+    deps;
+    bindings = [];
+    pending = [];
+    pendingTimer = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    register(def) {
+        const entry = { ...def, strokes: parseChord(def.keys) };
+        this.bindings.push(entry);
+        this.bindings.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        return toDisposable(() => {
+            const i = this.bindings.indexOf(entry);
+            if (i >= 0)
+                this.bindings.splice(i, 1);
+        });
+    }
+    unregister(keys, commandId) {
+        const strokes = parseChord(keys).join(' ');
+        this.bindings = this.bindings.filter((b) => !(b.strokes.join(' ') === strokes && (commandId === undefined || b.commandId === commandId)));
+    }
+    list() {
+        return this.bindings.map(({ strokes: _strokes, ...def }) => def);
+    }
+    forCommand(commandId) {
+        return this.bindings
+            // An argument-bearing binding is a key for one invocation, not for the
+            // command. `ctrl+shift+b` opens the palette at the sidebar panels; it is
+            // not the key for "Command Palette", and offering it as one put a wrong
+            // - and wider - hint beside that menu row.
+            .filter((b) => b.commandId === commandId && b.args === undefined)
+            .map((b) => b.keys);
+    }
+    applicable(binding) {
+        if (!this.deps.when.evaluate(binding.when))
+            return false;
+        if (!binding.scopeId)
+            return true;
+        return this.deps.activeScopes().includes(binding.scopeId);
+    }
+    handle(event) {
+        const stroke = strokeOf(event);
+        const sequence = [...this.pending, stroke];
+        let sawPrefix = false;
+        for (const binding of this.bindings) {
+            if (!this.applicable(binding))
+                continue;
+            const { strokes } = binding;
+            if (strokes.length === sequence.length && strokes.every((s, i) => s === sequence[i])) {
+                this.reset();
+                void this.deps.commands
+                    .execute(binding.commandId, binding.args ?? {}, 'keybinding')
+                    .catch((err) => this.deps.onError(err, `keybinding ${binding.keys}`));
+                return 'handled';
+            }
+            if (strokes.length > sequence.length &&
+                sequence.every((s, i) => strokes[i] === s)) {
+                sawPrefix = true;
+            }
+        }
+        if (sawPrefix) {
+            this.pending = sequence;
+            if (this.pendingTimer)
+                clearTimeout(this.pendingTimer);
+            this.pendingTimer = setTimeout(() => this.reset(), this.deps.chordTimeoutMs ?? 1200);
+            this.pendingTimer.unref?.();
+            return 'pending';
+        }
+        this.reset();
+        return 'unhandled';
+    }
+    reset() {
+        this.pending = [];
+        if (this.pendingTimer) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+    }
+}
+export function createKeybindings(deps) {
+    return new Keybindings(deps);
+}

package/dist/core/layers.d.ts

@@ -0,0 +1,28 @@
+import type { LayerEntry, LayerManager, LayerName } from '../types/layer.js';
+import type { Disposable } from '../types/disposable.js';
+/**
+ * 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 declare class Layers implements LayerManager {
+    private onChange;
+    private byId;
+    private timers;
+    private counter;
+    constructor(onChange?: () => void);
+    open(entry: LayerEntry): Disposable;
+    close(id: string, reason?: 'escape' | 'outside' | 'timeout' | 'api'): void;
+    closeLayer(layer: LayerName): void;
+    /** Sorted by plane, then by open order - which is paint order. */
+    entries(layer?: LayerName): LayerEntry[];
+    topmostTrap(): LayerEntry | null;
+    /** The entry Escape should close: the last dismissible one. */
+    topmostDismissible(): LayerEntry | null;
+    update(id: string, patch: Partial<LayerEntry>): void;
+    dispose(): void;
+}
+export declare function createLayers(onChange?: () => void): Layers;
+//# sourceMappingURL=layers.d.ts.map

package/dist/core/layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../src/core/layers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAKzD;;;;;;GAMG;AACH,qBAAa,MAAO,YAAW,YAAY;IAK7B,OAAO,CAAC,QAAQ;IAJ5B,OAAO,CAAC,IAAI,CAAiC;IAC7C,OAAO,CAAC,MAAM,CAAoD;IAClE,OAAO,CAAC,OAAO,CAAK;gBAEA,QAAQ,GAAE,MAAM,IAAe;IAEnD,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IAcnC,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,KAAa,GAAG,IAAI;IAkBjF,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAIlC,kEAAkE;IAClE,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,EAAE;IASxC,WAAW,IAAI,UAAU,GAAG,IAAI;IAKhC,+DAA+D;IAC/D,kBAAkB,IAAI,UAAU,GAAG,IAAI;IAKvC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAOpD,OAAO,IAAI,IAAI;CAKhB;AAED,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,CAE1D"}

package/dist/core/layers.js

@@ -0,0 +1,84 @@
+import { toDisposable } from '../util/disposable.js';
+const LAYER_ORDER = ['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 {
+    onChange;
+    byId = new Map();
+    timers = new Map();
+    counter = 0;
+    constructor(onChange = () => { }) {
+        this.onChange = onChange;
+    }
+    open(entry) {
+        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, reason = 'api') {
+        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) {
+        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) {
+        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() {
+        const trapping = this.entries().filter((e) => e.trapFocus);
+        return trapping[trapping.length - 1] ?? null;
+    }
+    /** The entry Escape should close: the last dismissible one. */
+    topmostDismissible() {
+        const list = this.entries().filter((e) => e.dismissOnEscape !== false);
+        return list[list.length - 1] ?? null;
+    }
+    update(id, patch) {
+        const entry = this.byId.get(id);
+        if (!entry)
+            return;
+        this.byId.set(id, { ...entry, ...patch });
+        this.onChange();
+    }
+    dispose() {
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        this.byId.clear();
+    }
+}
+export function createLayers(onChange) {
+    return new Layers(onChange);
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,22 @@
+import type { Manifest, ManifestAPI, ManifestSource } from '../types/manifest.js';
+import type { TextUIApp } from '../types/app.js';
+import type { Disposable } from '../types/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 declare class Manifests implements ManifestAPI {
+    private app;
+    private loaded_;
+    constructor(app: TextUIApp);
+    load(manifest: Manifest): Promise<Disposable>;
+    unload(sourceId: string): void;
+    sources(): ManifestSource[];
+    loaded(sourceId: string): boolean;
+}
+export declare function createManifests(app: TextUIApp): Manifests;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/core/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/core/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD;;;;;;;GAOG;AACH,qBAAa,SAAU,YAAW,WAAW;IAG/B,OAAO,CAAC,GAAG;IAFvB,OAAO,CAAC,OAAO,CAAyE;gBAEpE,GAAG,EAAE,SAAS;IAE5B,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;IAkDnD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI9B,OAAO,IAAI,cAAc,EAAE;IAI3B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAGlC;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,CAEzD"}

package/dist/core/manifest.js

@@ -0,0 +1,85 @@
+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 {
+    app;
+    loaded_ = new Map();
+    constructor(app) {
+        this.app = app;
+    }
+    async load(manifest) {
+        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;
+        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) {
+        this.loaded_.get(sourceId)?.disposable.dispose();
+    }
+    sources() {
+        return [...this.loaded_.values()].map((e) => e.source);
+    }
+    loaded(sourceId) {
+        return this.loaded_.has(sourceId);
+    }
+}
+export function createManifests(app) {
+    return new Manifests(app);
+}

package/dist/core/navigation.d.ts

@@ -0,0 +1,47 @@
+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';
+/**
+ * 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 declare class Navigation implements Navigator {
+    private deps;
+    private defs;
+    private entries;
+    constructor(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;
+    screens(): ScreenDefinition[];
+    get(id: string): ScreenDefinition | undefined;
+    private publish;
+    /** Remember where focus was, so `pop` can put it back. */
+    private snapshotFocus;
+    push(id: string, params?: Record<string, unknown>): void;
+    replace(id: string, params?: Record<string, unknown>): void;
+    pop(): boolean;
+    popTo(id: string): boolean;
+    reset(id: string, params?: Record<string, unknown>): void;
+    current(): ScreenEntry | null;
+    stack(): ScreenEntry[];
+    canGoBack(): boolean;
+    /** A screen's own scope dies with it, unless it asked to be kept alive. */
+    private clearScreenScope;
+}
+export declare function createNavigation(deps: ConstructorParameters<typeof Navigation>[0]): Navigation;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/core/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD;;;;;;GAMG;AACH,qBAAa,UAAW,YAAW,SAAS;IAKxC,OAAO,CAAC,IAAI;IAJd,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,OAAO,CAAqB;gBAG1B,IAAI,EAAE;QACZ,KAAK,EAAE,aAAa,CAAC;QACrB,KAAK,EAAE,YAAY,CAAC;QACpB,QAAQ,IAAI,IAAI,CAAC;QACjB;;;;;;WAMG;QACH,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;KACxC;IAGH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU;IAK9C,OAAO,IAAI,gBAAgB,EAAE;IAI7B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAI7C,OAAO,CAAC,OAAO;IAYf,0DAA0D;IAC1D,OAAO,CAAC,aAAa;IAKrB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IASxD,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAU3D,GAAG,IAAI,OAAO;IAWd,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAY1B,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMzD,OAAO,IAAI,WAAW,GAAG,IAAI;IAI7B,KAAK,IAAI,WAAW,EAAE;IAItB,SAAS,IAAI,OAAO;IAIpB,2EAA2E;IAC3E,OAAO,CAAC,gBAAgB;CAKzB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,qBAAqB,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAE9F"}

package/dist/core/navigation.js

@@ -0,0 +1,110 @@
+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 {
+    deps;
+    defs = new Map();
+    entries = [];
+    constructor(deps) {
+        this.deps = deps;
+    }
+    register(screen) {
+        this.defs.set(screen.id, screen);
+        return toDisposable(() => this.defs.delete(screen.id));
+    }
+    screens() {
+        return [...this.defs.values()];
+    }
+    get(id) {
+        return this.defs.get(id);
+    }
+    publish() {
+        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. */
+    snapshotFocus() {
+        const top = this.entries[this.entries.length - 1];
+        if (top)
+            top.restoreFocus = this.deps.focus.focused();
+    }
+    push(id, params) {
+        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, params) {
+        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() {
+        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) {
+        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, params) {
+        for (const entry of this.entries)
+            this.clearScreenScope(entry);
+        this.entries = [{ id, params }];
+        this.publish();
+    }
+    current() {
+        return this.entries[this.entries.length - 1] ?? null;
+    }
+    stack() {
+        return [...this.entries];
+    }
+    canGoBack() {
+        return this.entries.length > 1;
+    }
+    /** A screen's own scope dies with it, unless it asked to be kept alive. */
+    clearScreenScope(entry) {
+        if (!entry)
+            return;
+        if (this.defs.get(entry.id)?.keepAlive)
+            return;
+        this.deps.store.clearScope(`screen.${entry.id}`);
+    }
+}
+export function createNavigation(deps) {
+    return new Navigation(deps);
+}

package/dist/core/resources.d.ts

@@ -0,0 +1,115 @@
+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 type { SemanticVariant } from '../types/style.js';
+/**
+ * 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 declare class Resources implements ResourceRegistry {
+    private deps;
+    private kindDefs;
+    private providers;
+    private viewers;
+    private editors;
+    private actions;
+    constructor(deps: {
+        components: ComponentRegistry;
+        when: WhenEngine;
+    });
+    registerKind(kind: ResourceKind): Disposable;
+    registerProvider(provider: ResourceProvider): Disposable;
+    registerViewer(def: ResourceViewerDefinition): Disposable;
+    registerEditor(def: ResourceEditorDefinition): Disposable;
+    registerAction(def: ResourceActionDefinition): Disposable;
+    kinds(): ResourceKind[];
+    /** Extension, then mime type, then an explicit `detect`. Best match wins. */
+    detectKind(uri: ResourceURI, meta?: ResourceMetadata): string;
+    kindMatches(kind: string, ancestor: string): boolean;
+    private provider;
+    stat(uri: ResourceURI): Promise<Resource | null>;
+    list(uri: ResourceURI): Promise<Resource[]>;
+    read(uri: ResourceURI): Promise<string | Uint8Array>;
+    write(uri: ResourceURI, content: string | Uint8Array): Promise<void>;
+    /**
+     * 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.
+     */
+    delete(uri: ResourceURI): Promise<void>;
+    /**
+     * 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.
+     */
+    rename(from: ResourceURI, to: ResourceURI): Promise<void>;
+    /**
+     * 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;
+    viewersFor(kind: string): ResourceViewerDefinition[];
+    editorsFor(kind: string): ResourceEditorDefinition[];
+    /**
+     * 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;
+    };
+    renderersFor(kind: string): ResourceRendererDefinition[];
+    actionsFor(kind: string, slot?: string): ResourceActionDefinition[];
+    /**
+     * 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;
+}
+export declare function createResources(deps: ConstructorParameters<typeof Resources>[0]): Resources;
+//# sourceMappingURL=resources.d.ts.map