npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@estiva-app/interop

v0.107.0

Published

Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.

Readme

@estiva-app/interop

Render and act on another app's objects, from a manifest that app published. Your app learns nothing about theirs.

npm install @estiva-app/interop @estiva-app/protocol

No registry auth, no .npmrc, no token — ADR 0002 §3.

The one rule everything follows

The owner defines the projection. The consumer decides how it looks.

An app that owns objects publishes a NIP-89 kind:31990 manifest saying which of its fields matter, what its statuses mean, and what another app may do to them. It never says how to draw anything — an owner who could specify layout would be designing your product, which is the same objection that rules out iframes.

So this package returns values with enough shape to render, and no components. Nothing in it knows what any particular app is.


1. Render an object from an app you know nothing about

You are holding a reference somebody pasted — nostr:naddr1…, or a bare kind:pubkey:d. You do not know which app owns it.

import { resolveForeignObject } from '@estiva-app/interop'
import { Relay } from '@estiva-app/protocol'

const relay = new Relay('https://your.relay', signer)
const query = (filters) => relay.query(filters)

const object = await resolveForeignObject(reference, query)

query is the only thing this package touches the outside world with, and you supply it. There is no client inside, no global, and no configuration — which is also why the whole test suite runs with an array standing in for the relay.

What comes back:

{
  ref: '30851:abc…:9c69f247-…',   // stable handle, whatever the object is
  kind: 30851,
  appName: 'Estiva Ship',
  noun: 'issue',                  // what the owner calls one, if it says
  widget: 'row',                  // a hint. See §3
  slots: {
    title:    { value: 'Billing entry' },
    status:   { value: 'In Progress', colour: 'blue' },
    subtitle: { value: 'Settings entry point.' },
    body:     { value: '**Stripe Checkout** for billing.', format: 'marker' },
  },
  meta: [{ label: 'Assignee', value: 'abc…', isPubkey: true }],
  children: [ /* … more of the same, if the owner declared a list */ ],
  actions: [ /* … see §2 */ ],
  openUrl: 'https://ship.estiva.app/#/o/naddr1…',
  people: { 'abc…': { displayName: 'Ana', picture: '…' } },
}

Render the slots you implement and ignore the ones you do not. That is not politeness, it is required: the slot set is closed but it grows, and producers upgrade before consumers do. title is always present, so an object you only half understand still renders as a named, resolvable thing.

Holding a set? Resolve it as one

A list you keep live — followed files, open work — should not resolve its entries one at a time. Each resolve is a request, and a relay that meters reads per request (the Estiva relay allows 300 a minute, shared by a person's tabs) runs out on a refresh of a few dozen.

import { resolveForeignObjects, createProjectionCache } from '@estiva-app/interop'

const cache = createProjectionCache() // keep it for the session
const objects = await resolveForeignObjects(addresses, query, undefined, cache)
// { [address]: ForeignObject | null } — each exactly what resolveForeignObject returns

Every object keeps its own filters and limits, so a busy one never crowds out another's comments; they share the POST. A warm refresh of up to 32 objects is one request and a people lookup, plus one more for the whole set when a card lists children its app folds — their changes, so a moved or archived child is not drawn under its old parent (MAN-7). Event references (nevent) are not addresses and come back null; resolve those with resolveForeignEvent.

Where the relay offers the open read with text (NIP-11 file_list.text), pass the kinds you have switched as openRead — { openRead: [30850] } for projects. Each such file then costs its first record, one current change per field and one text, however long its history (SPEC §6.13), and every object carries prevs for the next change to name (prevOf(object, field)). A deleted file is read as before and comes back with deleted: { by, at }.

Need only where each file sits? Ask for that alone — the roots, and the moves where a kind can be moved, without anybody's comments or children:

import { resolveParents } from '@estiva-app/interop'

const parents = await resolveParents(addresses, query, cache)
// { [address]: parent address | null } — null at the top, no key when nothing can be told

Folded by the same rule as ForeignObject.parentRef, so a moved issue is under the project it was moved to here as everywhere else.

A body says which content model it is in — read it, do not guess

body is the one slot that carries structure, and it arrives in one of two models that must never be read as each other. The slot tells you which, so you never have to look at the text:

| slot.body.format | what you have | | --- | --- | | 'marker' | the marker dialect — **bold**, # heading, > quote, fenced code | | 'blocks' | a JSON block document | | 'unknown' | a model published after your app was written |

import { toRenderTree } from '@estiva-app/protocol'

// One tree, whichever model it came in. Marks decided, blocks decided,
// nothing left to parse — so you cannot render markup by accident.
const blocks = toRenderTree(object.slots.body.value, object.slots.body.format)

Never decide the model by inspecting the body. A description that happens to begin with { is marker text if its event carries no content-format tag, and there are hundreds of those already published. 'unknown' exists so you can decline: rendering a body you do not understand as plain text is correct, and guessing at it is not.

A slot that is not a body carries no format at all — that is how you tell "this is prose in the marker dialect" from "this is a title, and models do not apply to it".

The states you must draw, and the one that catches everyone

A foreign object has more failure states than anything else on your screen, because you control none of its lifecycle.

| state | how you know | | --- | --- | | resolved | you got an object | | you may not see it | object.unreachable === true | | nothing claims this kind | null | | declared a list, and it is empty | children is [] | | declared no list | children is undefined |

"You may not see it" and "it is empty" must never look the same. A gated read returns nothing at all — the same nothing as a thing with no content — so the relay cannot distinguish them and neither can you unless you use unreachable. Draw one state for both and you have built a screen that quietly lies.

2. Let a reader act on it, without an API

An action is an event to publish, never an endpoint to call. There is no server in the loop, and the owning app can be offline.

import { buildActionEvent, resolveManifest } from '@estiva-app/interop'

const resolved = await resolveManifest(object.kind, query)

const built = buildActionEvent({
  manifest: resolved.manifest,
  kind: object.kind,
  address: object.ref,
  objectAuthor: pointer.pubkey,
  folder,                       // the object's channel — see below
  actionId: 'set-issue-status',
  value: 'done',
  pubkey: me,                   // whoever is about to sign
  createdAtMs: Date.now(),
})

// A refusal is a string, and it is written for a person to read.
if (typeof built === 'string') return show(built)

await relay.publish(await signer.sign(built))

Some actions are another app's. An object also offers the creations other apps declare on its kind — Ship's New project on a Folder, which is Peek's — and such an action carries declaredBy. Build it with resolveActingManifest(pointer, action.declaredBy?.address, query) in place of resolveManifest: the owner's manifest does not declare it and refuses to.

Check the string. buildActionEvent returns UnsignedActionEvent | string, and the string is why it refused — an undeclared field, a required one left empty, a value outside the declared vocabulary, a person (type: "pubkey") that is not '' or 64 lowercase hex. A person it accepts is also written as ["p", <key>], which is what makes them a member of the file (SPEC §7.3, §11.8). Treat the result as an event without checking and you will sign the refusal.

Everything it needs is passed in rather than reached for: this package opens no socket, reads no clock and holds no identity, so the built event is a pure function of its inputs and the whole suite runs against an array.

object.actions is already resolved against the owner's vocabularies, so a select arrives with its options and the value it currently holds. Each option carries its declared stage when it is one of the four, so an app that builds its own change from a choice appends stageTagFor(field, value, action.options) last and says what the choice means, as buildActionEvent does (SPEC §7.3).

Actions that create an object, not just change one

An action with control: 'form' makes a whole new object rather than setting a field on this one. It arrives with the schema already resolved:

const action = object.actions.find((a) => a.control === 'form')

action.fields        // [{ name: 'title', type: 'string', required: true }, …]
action.createsUnder  // the address the new object will hang under

Draw the fields, then pass an object rather than a scalar, plus an id for the thing being made:

const built = buildActionEvent({
  /* …as above… */
  actionId: action.id,
  value: { title: 'Payment fails on retry' },
  newId: crypto.randomUUID(),
})

Declaring one, from the producer's side — required is a list of names, not a flag on each property:

{
  "id": "add-issue", "label": "Add issue", "appliesTo": "31800",
  "emits": { "kind": 31801, "setTag": "a", "toAddressOf": "self" },
  "input": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "note": { "type": "string", "target": "content" }
    },
    "required": ["title"]
  }
}

newId is required for an addressable kind and is supplied by you rather than generated here — an object published without one has no address at all, so nothing could reference it, comment on it or act on it afterwards.

Two rules worth knowing before you draw the form. A property's name is the tag its value is written to, which is what lets a consumer build an event for an app it has never seen. And one property may target the event's content instead, with "target": "content" — at most one, because an event has one body, and a consumer refuses the whole action rather than choosing between two.

That second rule is new in 0.13.0. Before it, nothing could be written to content at all, and the consequence was not a rough edge: an app whose object is its body — a message, a note, a comment — could not declare a create action at all, because a body in a tag is not a body. Peek's manifest said "actions": [] for exactly that reason.

A field carrying target reaches you on the resolved action, so you can draw prose where the producer meant prose. Ignoring it is safe — the event is correct either way; you will just have drawn a single-line input for a paragraph.

Two consequences worth knowing before you ship it. Validation is an honour system — nothing stops you publishing a status outside the declared vocabulary, and a consumer that skips the check is the one putting junk in a shared record. And an object with no naddr offers no actions: a change names its target with an a tag, and a regular event cannot be named that way. That is the model being honest, not a gap.

Actions that delete

An action whose emits.kind is 5 is a deletion, and it arrives as control: 'confirm' — one button, no value, ask first (its effect is destructive). buildActionEvent builds NIP-09's request naming the object's address, and the relay decides who may: the author, or the owner of an agent that wrote it. Offer it to everyone and report the answer. A consumer that hid the control behind an author check of its own would hide it from the one person the relay would have let through, and could never evaluate the second half anyway (SPEC §6.5).

const action = object.actions.find((a) => a.control === 'confirm')
// after the person has confirmed:
const built = buildActionEvent({ /* …as above… */ actionId: action.id, value: '' })

The bare file's built-in manifest declares one, beside rename (a title change) and comment. A consumer that draws every field-setting action as an input will now draw a "Rename" box under a bare file's card; whether that is what its card is for is the consumer's call, and the field it sets is the one slots.title.field names, so the two are one fact either way (PEEK-18).

It also declares move (a parent change; SPEC §6.7). Its value is an address, so a text box under a card is the wrong control for it: the object names the field in parentField, and a consumer drawing property rows keeps that one out, as it keeps the title's out, and offers the move where it draws the tree.

Moves, placement and prose (0.36.0)

Three things an owner declares so a consumer can do what the owner does (SPEC §7.2–7.3, MAN-1).

A move is a change to the field the parent's list names as movedBy:

"list": { "children": { "kind": 30851, "via": "a", "movedBy": "project" } }

The folded field wins over the child's a tag, and an empty value is a move to no parent. The object carries parentField (the bare file's is parent, now declared rather than hard-coded) and parentKind, the kind a move may name — nestingOf(...).moveTargetsOf offers only that kind.

A list may add "anyParent": true (0.56.0): the child names its own parent with its via tag, of any kind, as a bare file does, so parentKind is absent and a move may name any file in the Folder. Leaf's document (30842) declares it.

Placement and listing. A creation may name its Folder with buzz-channel instead of h, and an action declaring listed: true is followed by the kind:1852 that keeps the Folder's listing true. Those are built by buildActionEvents, which needs what only your read of kind:30890 knows — buildActionEvent refuses them rather than publish half:

const events = buildActionEvents({ /* …as above… */ actionId: 'add-project',
  value: { name: 'Launch' }, newId: crypto.randomUUID(), folderHasState: folder.hasState })
// [kind:30850 with buzz-channel, kind:1852 add] — publish in order, stop at the first refusal

buildActionEvents({ /* … */ actionId: 'delete-project', value: '', listedIn: folders })
// [kind:5, a kind:1852 remove per Folder with state]

A resolved action carrying listed: true is one that needs them.

Prose. A field declared with "format": "estiva-blocks-1" — on a creation's content property, or a change's input — arrives with format on the resolved field or action, so you can draw a block editor. Pass contentFormat: 'estiva-blocks-1' with a block document and the event carries content-format and an imeta per attached file; pass plain text without it and the value is written as marker text, which is always correct.

Replies

A reply is the comment action with a parent. Pass replyTo and the uppercase A/K/P still name the file while the lowercase trio names the comment answered — SPEC §6.4's table:

const built = buildActionEvent({ /* …as above… */ actionId: 'comment', value: 'Agreed.',
  replyTo: { id: comment.id, kind: comment.kind, author: comment.pubkey } })

kind is the parent's own, which for one of Ship's replies is 9. A reply carries no lowercase a, so the file's #a read (conversationsOf) never returns it. threadsOf is the read that does: the roots by id and their direct replies by #e, in one request for every thread.

const roots = (await conversationsOf([file], query))[file.ref].map((m) => m.id)
const { roots: byId, replies } = await threadsOf(file.address, roots, query)
// byId[id] is the root event; replies[id] its direct replies, oldest first

Nesting

nestingOf(files) draws a listing's nesting — roots, childrenOf, ancestorsOf (a breadcrumb), parentOf, moveTargetsOf — in memory, from the parentRef each file already carries. Hand it the whole team listing from resolveFolderContents, never the answer to a #a query: a move is a change event whose value no relay indexes, so "what is under X?" asked by tag misses every file moved in. A parent outside the listing is not drawn, and a file on a cycle is drawn at the top, so every listed file stays reachable and no walk loops.

Offering files to reference (0.46.0)

A composer's [ offers files as @estiva-app/conversation's rankReferences ranks them. fileCandidates(objects, tier, query) turns resolved objects — a Folder's listing, the files you read recently — into its rows: the type word from REFERENCE_FILE_TYPES, the current title, an issue captioned with its project's title. searchFileReferences(text, query) is the search tier: it asks the relay for roots and title changes holding the word, resolves each address through its manifest, and keeps only the files whose current title matches. Pass it to conversation's referenceSearch. Neither offers what the reader could not resolve.

3. Widgets: draw what you know, degrade honestly

widget is a layout hint, and it may be a single type or an ordered chain:

"widget": ["message", "card"]   // a message if you know it, else a card

A chain always ends in one of card, row, table, stat, so there is always something you can draw.

import { pickWidget, CLOSED_WIDGETS } from '@estiva-app/interop'

const layout = pickWidget(object.widget, ['message', ...CLOSED_WIDGETS], 'card')

Never render nothing. An object that is present but blank is indistinguishable from one the reader is not allowed to see, and reports "that app is broken" about an app that is behaving correctly.


4. Make your objects renderable by other apps

Publish one kind:31990. Here is a hiring tool declaring a Candidate — an app this suite knows nothing about, which is the point.

{
  "name": "Hiring",
  "records": {
    "changeKind": 1851, "targetTag": "a", "fieldTag": "field", "valueTag": "value",
    "order": ["ts", "created_at", "id"], "rule": "last-write-wins-per-field"
  },
  "projections": {
    "31800": {
      "widget": ["candidate", "card"],
      "slots": {
        "title":    { "tag": "name" },
        "subtitle": { "tag": "headline", "truncate": 120 },
        "status":   { "fold": "stage", "map": "stages", "default": "applied" },
        "meta":     [{ "label": "Recruiter", "fold": "owner", "as": "pubkey" }],
        "list":     { "children": { "kind": 31801, "via": "a", "limit": 50 } }
      }
    }
  },
  "vocabularies": {
    "stages": [
      { "value": "applied",   "label": "Applied",   "colour": "neutral", "stage": "open" },
      { "value": "screening", "label": "Screening", "colour": "blue",    "stage": "started" },
      { "value": "hired",     "label": "Hired",     "colour": "green",   "stage": "done" },
      { "value": "passed",    "label": "Passed",    "colour": "muted",   "stage": "dropped" }
    ]
  },
  "actions": [
    {
      "id": "set-stage", "label": "Change stage", "appliesTo": "31800",
      "emits": { "kind": 1851, "field": "stage" },
      "input": { "type": "string", "enum": "stages" },
      "description": "Move a candidate to a different hiring stage",
      "effect": "writes"
    }
  ]
}

A chat app now renders your candidate — with your stages, your colours, your recruiter — in its design language, and lets someone move a stage without leaving the conversation. It knows nothing about hiring.

Six things that will bite, each of them something we got wrong first:

  • title is required. It is what makes ignoring an unknown slot safe.
  • A mutable field must be a fold, never a tag. A status that can be set by someone who is not the author does not live on the root event, so a tag renders empty for ever.
  • stage says what a status means. Without it a consumer reporting progress has to guess from your label, and the only way to guess is a list of English words — which fails for the next app that spells things differently. dropped is the one nothing can infer: neither outstanding nor progress.
  • Never truncate a field that carries structure. truncate is a plain-text operation. A subtitle promises plain text; a body carries structure. Cut markdown at 120 characters and you have published 120 characters of markup.
  • A widget chain must terminate in a closed type. ["candidate"] is not publishable. widgetChainProblem() is exported so you can check before you sign — a manifest is read by apps that cannot ask what you meant.
  • An action's description is read by a machine, not shown on a button. A caller choosing between every action every app declares has that prose and nothing else. "Add" is not rejected anywhere — your action is simply never the one chosen, and nothing tells you. actionProblems() is exported for the same reason as the check above: run it in your own tests before you sign.
  • Your objects need a Folder tag to be actionable. A consumer finds where to write by reading h, then the relay's buzz-channel, on the object being acted on; an object carrying neither is refused for having nowhere to go. folderOf() is exported so you can check what a consumer will conclude about your records.

If you own no kinds, say which aspect you render

The hiring tool above is a specialized app: it owns a kind and draws every part of it. A generic app owns nothing and renders one aspect of every file in the workspace — a chat app draws each file's conversation, a writing app each file's document (RFC 0.5 §10.7). Its manifest says so with one field:

{ "name": "Peek", "aspect": "conversation", "fileNoun": "topic", "projections": {} }

What a consumer does with it today: a bare file (kind:30840, SPEC §6.7) has no owner and so no web template of its own, and the app that renders its conversation is where a link to it belongs. Publish aspect and a web template for naddr on the same kind:31990, and every consumer's card for a topic becomes a link into your app — with no change on their side. ASPECTS is exported and holds the two values.

The bare file is then named after your app too: its appName is your name, and its noun is your fileNoun — what your people call a file nobody owns, lower case and singular. Leave fileNoun out and the file has no noun, and a consumer falls back to your app's name. Nothing else in your manifest applies to a bare file; its slots, fold rule and actions are the runtime's.

The same is true of a comment (kind:1111): every app writes one and none owns it, so the built-in manifest draws it — the author as its title, the text as its body, with the message widget — and it opens by your nevent template. Publish one, or one web string for both entity types.

So is a chat message (kind:9, SPEC §7.8, 0.58.0), drawn the same way with the noun "message", and a Folder (kind:39000, §3.2): its name as the title, its about as the subtitle, the noun "folder", opened by your naddr template. Do not claim either with a k tag; the runtime never asks. A Folder's contents are what resolveFolderContents reads (section 5), not a list slot; a card that lists them under the name resolves the Folder with { folderFiles: true } and draws its children, the files this reader can open, and a chip leaves it off and reads nothing more. What every app may do in one — New file, Start a conversation — comes with it, declared by FOLDER_ACTIONS_ADDRESS.

Say what your links look like

A URL somebody pastes is a reference too (RFC 0.5 §7.5). Declare each shape you serve as a urls tag on the manifest event, with the kind it names:

["urls", "https://peek.estiva.app/topic/<slug>-<d>", "30840"]
["urls", "https://peek.estiva.app/topic/<slug>-<d>?thread=<id>", "1111"]
["urls", "https://peek.estiva.app/message/<id>", "9"]

<d> resolves with #d, <id> with ids; the slug is decoration. A placeholder in the query is the identity, and the path's is then the container (within). A consumer calls matchObjectUrl(url, urlPatternsOf(manifest)) and gets { identifier, by, kind } or null — a URL nothing claims is a link and stays one.


5. Read a whole folder, across every app in it

A Folder is where the suite's navigation lives: teams you belong to, and the files inside them. resolveFolderContents answers "what is in this folder?" without knowing what any of the answers are.

import { resolveFolderContents, createProjectionCache } from '@estiva-app/interop'

const cache = createProjectionCache()
const folder = await resolveFolderContents(folderId, query, undefined, cache)

folder.name                       // the folder names itself
folder.files                      // ForeignObjects, exactly as §1 draws them
folder.source                     // 'state' | 'channel' — see below

Every file comes back as the same ForeignObject §1 renders, so a folder view is §1 in a loop. A project from one app and a topic from another sit side by side as peers, because RFC 0.4 §5.2 established that one tag type — a — names every file, topics included. Nothing here special-cases either.

Reuse one ProjectionCache across folders. Round trips are flat in the number of files and linear in the number of apps: 24, 25 and 9 files measured at 5, 5 and 4 requests warm.

A deleted file (SPEC §6.5) stays listed in its Folder, and no list returns it. An Archive's Deleted filter reads them on its own, when it is drawn: resolveDeletedFiles(folderId, query, people, cache, { listRead }) answers the Folder's deleted files, each with deleted: { by, at }; with listRead only the files the list read leaves out are read whole.

A whole tree: one load query

A sidebar reads listFolders, then each Folder's contents, and both read every change naming every listed file. Pass both the same createLoadQuery(query) and each change is asked of the relay once: a value whose changes came back whole is not asked again, and a read already in flight is joined.

import { listFolders, resolveFolderContents, createLoadQuery } from '@estiva-app/interop'

const load = createLoadQuery(query) // one per load: a refresh makes a new one
const folders = await listFolders(load)
const contents = await Promise.all(folders.map((f) => resolveFolderContents(f.id, load, undefined, cache)))

It holds the relay's answer at the moment of the load, so it is dropped after: kept across loads, a live list would stop seeing changes. Measured as the agent on production, 26 Oct: 70.7 MB and 39 requests became 23.9 MB and 31, the same listing byte for byte.

A read of a whole kind, { kinds: [1851] }, counts the same way: once it came back whole, a later read of that kind by one tag is answered from it. A query that pages every filter to its end, as Relay.queryAll does, says so, and then every answer counts however long it is:

const load = createLoadQuery((filters) => relay.queryAll(filters), { paged: true })

Measured as the agent's ship issues on production, 28 Oct, with the workspace read and the listing sharing one: 99.1 MB in 55 requests became 44.4 MB in 19, each change read once and the output byte for byte the same.

Only the kinds you draw

A reader that draws some kinds and no dots, such as a list of one app's files, need not pay for the rest:

const folders = await listFolders(query, { recordChannels: false }) // the Folders' own archives only
const topics = await resolveFolderContents(id, query, undefined, cache, { kinds: [KIND_BARE_FILE, KIND_CHANNEL_METADATA] })

recordChannels: false leaves out a record's channel (a Ship project's conversation) placed under the Folder that lists the record and archived with it; such a channel has no state, so topLevelFolders is the same. kinds reads and returns only the listed files of those kinds, every rule still applied — a parent of another kind is read as a link reads it. Measured as the agent listing Peek topics on production, 26 Oct: 149 s and 22.8 MB for the listing, 75 s and 11 MB for one Folder, almost all of it changes to files the list never drew.

A file you cannot see is absent, not greyed out

The count is the disclosure. A folder that renders three rows and two placeholders has told an outsider exactly how much they are missing, which for a folder named after a person is the sensitive part. So an address that resolves to nothing is dropped, and nothing in the return value counts what was dropped.

This is a deliberate divergence from upstream NIP-MP, whose fold requires the opposite for public repositories. It is also why this does not reuse resolveForeignObject, which returns unreachable: true — right for one pasted link, wrong for a list.

source tells you which model you are looking at

'state' means the relay maintains the folder's contents. 'channel' is the approximation available before that exists: containment read off each file's own h tag. It lists an app's records perfectly well and cannot list a topic, because under h a topic is the container rather than something inside it. A UI explaining a short list should read this field.

A sidebar

import { listFolders, topLevelFolders } from '@estiva-app/interop'

const folders = await listFolders(query)   // { id, name, hasState, private?, admins?, listedIn?, addresses?, channel?, archived? }[]
const teams = topLevelFolders(folders)     // state, nothing lists it, not archived

Asks for folders by kind rather than walking anything else. Discovering things only through their parent loses them when the parent goes — the failure RFC 0.4 §4.2 records, one level up from where it was first paid for.

A channel is addressable, so a folder can be a file in another folder — Peek's topics are, each listed by its team's state. listedIn names those containers, read off the states the call already holds, so a sidebar draws the team and not, beside it, every topic in it. topLevelFolders is that choice — a folder with state that nothing lists — so two apps draw the same sections.

addresses is the other direction: what a folder's state lists, unresolved and in order. An app drawing its own records under a team intersects it with the records it holds; one drawing another app's files resolves the folder.

A record a state lists places its own channel there too: a project's conversation lives in the channel its buzz-channel (or h) names, and that channel's listedIn is every Folder that lists the project, so an unread verdict on it has a team to reach. It costs one more request, for the records. A channel with state of its own is a Folder, and only states place it.

Changing a folder

import { planMoveFile } from '@estiva-app/interop'

const here = await resolveFolderContents(from.id, query)
const plan = planMoveFile(me, Date.now(), {
  file,                                                 // a ForeignObject from `here.files`
  listing: here.files,                                  // what is listed beneath `file` moves with it
  from: { id: here.id, hasState: here.hasState },       // from a read, never a guess
  to: { id: there.id, hasState: there.hasState, private: there.private },
})
if (!plan.ok) return plan.reason   // 'source-has-no-state' | 'target-has-no-state' | 'target-is-private'
for (const event of plan.events) { // publish in order; stop at the first refusal
  if (!(await publish(await sign(event))).ok) break
}

The planners are SPEC §3.3's operations — planCreateFolder, planRenameFolder, planArchiveFolder, planDeleteFolder, planPlaceFile, planUnlistFile, planMoveFile and planMoveFromFolders — and return unsigned events in publish order. Signing and publishing stay yours.

A move is one kind:1852 move in the target, naming the source in from and the file with every file listed beneath it (listedBeneath). The relay changes both lists in one write or neither, so the subtree is never split and a topic is never on no list. Into a private Folder it is refused when any moved file's h is another channel, or absent: a listing never changes who can read a file (§3.1).

A file can be listed in more than one Folder. To move it out of all of them, use planMoveFromFolders, which takes every Folder that lists it and each one's listing. It plans one move per source, each naming what that source lists. A file listed nowhere is placed instead, with one add. Publish the events in order and stop at the first refusal; what landed stands, and moving again finishes it. Read those listings with includeArchived, or an archived file beneath the one you move stays behind:

const listings = new Map(await Promise.all(sources.map(async (folder) =>
  [folder.id, (await resolveFolderContents(folder.id, query, noPeople, cache, { includeArchived: true })).files] as const)))
const plan = planMoveFromFolders(me, Date.now(), { file, from: sources, to, listings }) // sources: FolderSummary[], with addresses
if (!plan.ok) return plan.reason
for (const event of plan.events) if (!(await publish(await sign(event))).ok) return 'refused' // the relay's reason says why

No command carries a name: the title is the kind:39000's, so a rename is the kind:9002 alone and listFolders reads the title from the channel.

Place, unlist and move take hasState, because the relay computes a folder's next state from its current one and a group with no kind:30890 has none: a kind:1852 against it emits state listing only what the command named, and everything filed in it by h stops being listed. So place and unlist send no command to such a group, and a move into or out of one is refused.

listing is required; pass null only for a file nothing can sit beneath, so a move that leaves sub-files behind is never an accident.

Delete is for an empty Folder. The relay refuses a kind:9008 while the Folder holds a file, with a reason naming the count (folder holds 2 file(s) …). Its wording is the relay's. Take the count and say it in your app's words ("This Folder still has 2 files. Move or delete them first."), as you would for target-is-private.

A topic's list of files (0.71.0)

A topic lists files from any Folder, one kind:1851 entry per file, by the file's id (SPEC §6.14). The file stays where it is filed; a listing grants, moves and archives nothing.

import { planListInTopic, planRemoveFromTopic, topicList, topicsOfFile, folderOf } from '@estiva-app/interop'

const topic = { address: topicAddress, folder: folderOf(topicRoot)! } // the Folder its root names
const [entry] = planListInTopic(me, Date.now(), { topic, file: projectId }) // or planRemoveFromTopic
await publish(await sign(entry))

const files = await topicList(query, topicAddress)   // [{ file, address, entry }], in no promised order: sort as your design says
const shown = files.filter((f) => f.address)         // address null: unreadable, or two files hold the id
const topics = await topicsOfFile(query, projectId)  // [{ address, root, entry }]: which topics list it
const lists = await topicLists(query, myTopics)      // Map<topicAddress, files>: a whole column of topics in three reads
const read = await readTopics(query, me)             // every topic: list, Folder, archive, yours — Add to topic is addableTopics(read, folders)
const talk = await topicConversations(read, query, { merged, muted }) // Map<topicAddress, { conversations, unread }>, Peek's badge
const mine = await readYourTopics(query, me, { decrypt, listRead }) // a sidebar's: { topics, at, muted }, yours alone, newest activity first

topicsOfFile asks {kinds:[1851], "#o":[id]}; a file's own changes, by #O or #a, never hold an entry that lists it. Only topics' lists are read, an entry filed outside its topic's Folder is ignored, and an id held by two files or only by a Folder resolves to nothing: draw and count only the resolved ones. topicList resolves ids over LISTED_FILE_KINDS; pass fileKinds for kinds you know from manifests.

Archiving anything (0.37.0)

import { archiveImpact, isArchived, planArchiveFolder } from '@estiva-app/interop'

const impact = await archiveImpact(file.address, query)  // { hides: [{ kind, count }], staysVisible }
// …say what it hides, take a resolution, then publish the declared `archive`
// action with `value: 'true'` and `note: resolution` — or, for a Folder:
const [change] = planArchiveFolder(me, Date.now(), { folder: f.id, channel: f.channel!, archived: true, resolution })

const opened = await resolveForeignObject(link, query, people, 0, cache, { archivedWith: true })
if (isArchived(opened)) showBanner(opened.archived)       // { by, at, resolution?, with? }

One field for every file, whatever its kind: a change setting archived to 'true' on the file's address archives it and an empty value restores it. It is a change, so anyone who may write in the Folder may, and the change's content is the resolution a person gave. A Folder itself is the exception (SPEC §3.2): its archive counts only from an owner or admin on its kind:39001 — or, on a team whose 39001 lists no owner, from the workspace's owners and admins on the relay's roster (kind:13534) — published in its own h. Offer Archive on a Folder only to folder.admins, which holds both.

The cascade is read, never written. A Folder's contents leave out an archived file and everything under it — an issue with its project, a sub-topic with its topic — and topLevelFolders leaves out an archived Folder, so its subtree goes too. Nothing is written to the children, so unarchiving restores exactly what was there, and a file another Folder also lists stays visible in that one. A link still opens an archived file, with archived set — with naming the parent when it is archived only with it — so the page can draw the resolution first and an Unarchive control.


What is not in here, deliberately

No fold. Manifest semantics are normative; an app's interpretation of its own records is not. Two apps folding the same events are supposed to be able to differ (SPEC §10).

No rendering. Not a React dependency, not a component. A package that shipped a widget would be specifying the UI of every app that installed it.

No relay client. @estiva-app/protocol has two; this takes a function.

The specification, which outranks this package

SPEC §7 is normative and must stay sufficient to implement all of this without installing anything. If this package ever becomes the only place that knows how projection works, an interop standard has quietly been traded for a monoculture — and then a defect in it is a defect in every app at once, invisible from all of them.

The package is a reference implementation. The specification is the standard. In that order.