@estiva-app/interop 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,82 @@ how a declaration is read, is a MAJOR — in `0.x`, a MINOR — even when no
 TypeScript signature moved. A consumer upgrading must be able to tell whether
 manifests already published still mean what they meant.
 
+## 0.10.0 — 2026-09-03
+
+**RFC 0.5 §7's URL grammar, which was accepted with amendments today.** No
+existing manifest changes meaning; this adds a shape an app MAY declare and the
+matching a consumer needs to read it.
+
+### Added
+
+- **`slugify`, `objectRef`, `identifierFromRef`** — `<type>/<slug>-<d>`, built
+  and read. **Moved from Peek** (`src/lib/objectUrl.ts`, PEE-14) rather than
+  rewritten, with its cases, because an extraction that changes behaviour while
+  every test still passes is the thing to guard against.
+
+  Here rather than in each app because §7.1's argument is that the URL one app
+  puts in the address bar must be resolvable by another — SPEC §10's test for
+  something the protocol owns. Two implementations would disagree about what a
+  slug may contain, and the disagreement shows up as a link that resolves only
+  in the app that wrote it. Ship was about to grow the second copy (SHI-16).
+
+- **`urlPatternsOf`, `matchObjectUrl`, `UrlPattern`, `MatchedObjectUrl`** —
+  §7.5's inbound half: given a pasted link and the shapes apps publish, recover
+  which object it names. A URL no pattern claims returns `null`, which is the
+  honest outcome — it is a link, and nothing should claim otherwise.
+
+### The amendment this implements
+
+§7.2 said a consumer MUST ignore *everything* before the final uuid, which
+contradicted the paragraph above it and, read literally, resolves
+`evil.example.com/issue/<uuid>` as a Ship issue. **The host and the `<type>`
+segment select the app and the kind; only the slug is decoration**, and
+`matchObjectUrl` enforces that. It is the difference between a resolver and a
+gadget for rendering an attacker's chosen object inside your app.
+
+### One thing §7.5 leaves open, decided here
+
+A bare pattern tells a consumer *which app*, not which kind: `/issue/` means
+`30851` only to the app serving it. So `urls` MAY carry the kind as a third tag
+element. When it does not, a consumer falls back to the kinds that manifest
+declares it handles — sound because no `d` is reused under two kinds, measured
+across all 280 production records at §7's acceptance.
+
+## 0.9.1 — 2026-09-03
+
+**No behaviour change. The README was wrong, and this is the release that fixes
+the page people are told to start from** (PRO-9).
+
+- **§2's example did not compile, and its copy-paste path published an error
+  message.** It called `buildActionEvent({ object, actionId, value })`, which is
+  not the signature: the function takes the manifest, the kind, the address, the
+  object's author, the folder, the signer's pubkey and a clock, because this
+  package reaches for none of them. And it returns `UnsignedActionEvent | string`
+  where **the string is the refusal** — the example signed and published the
+  result without checking, so a reader following it would have put the words
+  "This app does not offer …" on the relay.
+
+- **The content model was undocumented.** `ResolvedSlot.format` shipped in 0.7.0
+  and a body cannot be rendered safely without it: §13 forbids reading either
+  content model as the other, and the page said nothing about which one you
+  have. Now a table of the three values, `toRenderTree`, and the rule that the
+  format is decided by the declaration and never by looking at the body.
+
+- **Object-creating actions were undocumented** — `control: 'form'`, `fields`,
+  `createsUnder`, and passing an object plus a `newId`, all shipped in 0.6.0.
+  With the producer's side too, since `required` is a list of names on `input`
+  rather than a flag on each property, which is the sort of thing a page is for.
+
+### Added
+
+- **`test/readme.test.ts` — the README, executed.** Every assertion is a claim
+  the page makes in prose, and it lives in `test/` so `npm run typecheck`
+  compiles it against the real declarations. The published example, pasted in
+  verbatim, fails that pass with `TS2353: 'object' does not exist in type`.
+
+  The page's examples had been run once, in a scratch project, when the package
+  was first published. That is a snapshot; this is a check.
+
 ## 0.9.0 — 2026-09-02
 
 **Behaviour unchanged, and no export moved.** `contentFormatOf`,

package/README.md

@@ -55,6 +55,7 @@ What comes back:
     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 */ ],
@@ -69,6 +70,36 @@ 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.
 
+### 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 |
+
+```ts
+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,
@@ -94,16 +125,89 @@ 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.
 
 ```ts
-import { buildActionEvent } from '@estiva-app/interop'
-
-const unsigned = buildActionEvent({ object, actionId: 'set-issue-status', value: 'done' })
-const signed = await signer.sign(unsigned)
-await relay.publish(signed)
+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))
 ```
 
+**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. 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.
 
+### 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:
+
+```ts
+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:
+
+```ts
+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:
+
+```jsonc
+{
+  "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" } },
+    "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 **nothing can target an event's `content`** — an app
+whose body lives there cannot have it filled from outside, which is why an
+action may declare a `description` field that ends up in a tag.
+
 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

package/dist/index.d.ts

@@ -25,4 +25,13 @@
  * iframes.
  */
 export { resolveManifest, resolveForeignObject, resolveForeignEvent, resolveFolderProject, commentKindsOf, buildActionEvent, pickWidget, widgetChainProblem, CLOSED_WIDGETS, contentFormatOf, BODY_SLOT, CONTENT_FORMAT_TAG, BLOCK_DOCUMENT_FORMAT, type ContentFormat, peopleViaRelay, createProjectionCache, createPeopleCache, MANIFEST_TTL_MS, PROFILE_HIT_TTL_MS, PROFILE_MISS_TTL_MS, type PeopleCache, type PeopleCacheOptions, type ProjectionCache, type ResolvedManifest, type QueryFn, type PeopleFn, type People, type ForeignObject, type FolderProject, type ResolvedSlot, type ResolvedAction, type ActionFormField, type ManifestAction, type ActionEffect, ACTION_EFFECTS, type UnsignedActionEvent, } from './projection.js';
+/**
+ * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
+ * a pasted link is matched back to one.
+ *
+ * Separate from the projection surface above because it answers a different
+ * question: those resolve an object you already hold, these turn a string
+ * somebody pasted into one you can hold.
+ */
+export { slugify, objectRef, identifierFromRef, urlPatternsOf, matchObjectUrl, type UrlPattern, type MatchedObjectUrl, } from './objectUrl.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,aAAa,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,aAAa,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA;AAExB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -25,4 +25,13 @@
  * iframes.
  */
 export { resolveManifest, resolveForeignObject, resolveForeignEvent, resolveFolderProject, commentKindsOf, buildActionEvent, pickWidget, widgetChainProblem, CLOSED_WIDGETS, contentFormatOf, BODY_SLOT, CONTENT_FORMAT_TAG, BLOCK_DOCUMENT_FORMAT, peopleViaRelay, createProjectionCache, createPeopleCache, MANIFEST_TTL_MS, PROFILE_HIT_TTL_MS, PROFILE_MISS_TTL_MS, ACTION_EFFECTS, } from './projection.js';
+/**
+ * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
+ * a pasted link is matched back to one.
+ *
+ * Separate from the projection surface above because it answers a different
+ * question: those resolve an object you already hold, these turn a string
+ * somebody pasted into one you can hold.
+ */
+export { slugify, objectRef, identifierFromRef, urlPatternsOf, matchObjectUrl, } from './objectUrl.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAenB,cAAc,GAEf,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,SAAS,EACT,kBAAkB,EAClB,qBAAqB,EAErB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EAenB,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,EACP,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,cAAc,GAGf,MAAM,gBAAgB,CAAA"}

package/dist/objectUrl.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Object URLs — RFC 0.5 §7, accepted 2026-09-03.
+ *
+ *     https://<app>.estiva.app/<type>s              a directory of that kind
+ *     https://<app>.estiva.app/<type>/<slug>-<d>    one object
+ *
+ * **Here rather than in each app** because it is wire-visible: §7.1's whole
+ * argument is that the URL one app puts in the address bar has to be resolvable
+ * by another, which is SPEC §10's test for something the protocol owns. Two
+ * implementations would disagree about what a slug may contain, and the
+ * disagreement would show up as a link that resolves in the app that wrote it
+ * and nowhere else.
+ *
+ * Peek's `src/lib/objectUrl.ts` is where `slugify`, `objectRef` and
+ * `identifierFromRef` were written (PEE-14) and they are moved rather than
+ * rewritten — an extraction that changes behaviour while every test still
+ * passes is the thing to guard against, so Peek's own cases come with them.
+ *
+ * Two properties from §7.2 do all the work:
+ *
+ *   - **The uuid is the whole identity and is never truncated.** A consumer
+ *     resolves `{"#d": ["<uuid>"]}` — one query, no index, and no service that
+ *     can go down and take every published link with it.
+ *   - **The slug is decorative.** Renaming the object changes it and the link
+ *     still resolves, because a reader ignores everything between the `<type>`
+ *     segment and the final uuid.
+ *
+ * That second sentence is the amended one. §7.2 used to say a consumer MUST
+ * ignore *everything* before the final uuid, which contradicted the paragraph
+ * above it and, read literally, resolves `evil.example.com/issue/<uuid>` as a
+ * Ship issue. The host and the `<type>` segment are exactly what select the app
+ * and the kind; only the slug is decoration. `matchObjectUrl` implements the
+ * corrected rule.
+ */
+/**
+ * A title reduced to URL-safe words. Decorative by contract: nothing resolves
+ * through it, so it is free to be lossy — accents folded, punctuation dropped,
+ * runs collapsed.
+ */
+export declare function slugify(title: string): string;
+/** `<slug>-<identifier>`, or the bare identifier when the title slugs to nothing. */
+export declare function objectRef(identifier: string, title?: string): string;
+/**
+ * The identity out of a ref, or `null` if it carries none.
+ *
+ * Lowercased on the way out: the relay's `d` values are lowercase uuids, and a
+ * link that has been through a system which upper-cased it should still resolve
+ * rather than silently miss.
+ */
+export declare function identifierFromRef(ref: string): string | null;
+/**
+ * A URL shape an app says it serves — RFC 0.5 §7.5's `urls`, read off the
+ * manifest event the way `web` is.
+ *
+ * `web` is outbound (given an object, build a link); this is inbound (given a
+ * link, recover the object). Usually the same strings, separate fields because
+ * they answer different questions — and because an app that changes its routes
+ * still has to read the links it published under the old ones.
+ */
+export interface UrlPattern {
+    /** e.g. `https://ship.estiva.app/issue/<slug>-<d>` */
+    pattern: string;
+    /**
+     * The kind this shape names, when the app said so.
+     *
+     * §7.2 says the kind comes from the path segment — but `/issue/` means 30851
+     * only *to the app serving it*, and a consumer has never heard of "issue".
+     * So an app MAY name the kind alongside the pattern. When it does not, a
+     * consumer falls back to the kinds the manifest declares it handles, which is
+     * sound because no `d` is reused under two kinds — measured across all 280
+     * production records at §7's acceptance.
+     */
+    kind?: number;
+}
+/** The `urls` shapes a manifest event declares. */
+export declare function urlPatternsOf(event: {
+    tags: string[][];
+}): UrlPattern[];
+/** What a pasted URL turned out to name. */
+export interface MatchedObjectUrl {
+    identifier: string;
+    /** Present only when the matched pattern named one. */
+    kind?: number;
+}
+/**
+ * Match a pasted URL against one app's declared shapes.
+ *
+ * **The host and the `<type>` segment are significant; the slug is not.** That
+ * is §7.2 as amended, and it is the whole of the security story here: a
+ * consumer that matched on the trailing uuid alone would resolve any URL from
+ * anywhere as that app's object.
+ *
+ * Returns null for a URL no pattern claims, which is the honest outcome — §7.5
+ * says such a URL renders as a plain link, because it is one.
+ */
+export declare function matchObjectUrl(url: string, patterns: UrlPattern[]): MatchedObjectUrl | null;
+//# sourceMappingURL=objectUrl.d.ts.map

package/dist/objectUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectUrl.d.ts","sourceRoot":"","sources":["../src/objectUrl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAkBH;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS7C;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,mDAAmD;AACnD,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,GAAG,UAAU,EAAE,CAQvE;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,gBAAgB,GAAG,IAAI,CAuB3F"}

package/dist/objectUrl.js

@@ -0,0 +1,158 @@
+/**
+ * Object URLs — RFC 0.5 §7, accepted 2026-09-03.
+ *
+ *     https://<app>.estiva.app/<type>s              a directory of that kind
+ *     https://<app>.estiva.app/<type>/<slug>-<d>    one object
+ *
+ * **Here rather than in each app** because it is wire-visible: §7.1's whole
+ * argument is that the URL one app puts in the address bar has to be resolvable
+ * by another, which is SPEC §10's test for something the protocol owns. Two
+ * implementations would disagree about what a slug may contain, and the
+ * disagreement would show up as a link that resolves in the app that wrote it
+ * and nowhere else.
+ *
+ * Peek's `src/lib/objectUrl.ts` is where `slugify`, `objectRef` and
+ * `identifierFromRef` were written (PEE-14) and they are moved rather than
+ * rewritten — an extraction that changes behaviour while every test still
+ * passes is the thing to guard against, so Peek's own cases come with them.
+ *
+ * Two properties from §7.2 do all the work:
+ *
+ *   - **The uuid is the whole identity and is never truncated.** A consumer
+ *     resolves `{"#d": ["<uuid>"]}` — one query, no index, and no service that
+ *     can go down and take every published link with it.
+ *   - **The slug is decorative.** Renaming the object changes it and the link
+ *     still resolves, because a reader ignores everything between the `<type>`
+ *     segment and the final uuid.
+ *
+ * That second sentence is the amended one. §7.2 used to say a consumer MUST
+ * ignore *everything* before the final uuid, which contradicted the paragraph
+ * above it and, read literally, resolves `evil.example.com/issue/<uuid>` as a
+ * Ship issue. The host and the `<type>` segment are exactly what select the app
+ * and the kind; only the slug is decoration. `matchObjectUrl` implements the
+ * corrected rule.
+ */
+/**
+ * A v4 uuid at the very end of a ref.
+ *
+ * Anchored at the end rather than searched for, because §7.2's rule is
+ * positional: the identity is the tail, and everything before it is a human
+ * label that may itself contain hyphens, digits and hex.
+ */
+const TRAILING_UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Slugs are cut here. Long enough to stay recognisable in a chat client's link
+ * preview, short enough that the uuid is not pushed off the end of a rendered
+ * URL — which is the only thing in the ref that carries meaning.
+ */
+const SLUG_MAX_LENGTH = 60;
+/**
+ * A title reduced to URL-safe words. Decorative by contract: nothing resolves
+ * through it, so it is free to be lossy — accents folded, punctuation dropped,
+ * runs collapsed.
+ */
+export function slugify(title) {
+    return title
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, SLUG_MAX_LENGTH)
+        .replace(/-+$/g, '');
+}
+/** `<slug>-<identifier>`, or the bare identifier when the title slugs to nothing. */
+export function objectRef(identifier, title) {
+    const slug = title ? slugify(title) : '';
+    return slug ? `${slug}-${identifier}` : identifier;
+}
+/**
+ * The identity out of a ref, or `null` if it carries none.
+ *
+ * Lowercased on the way out: the relay's `d` values are lowercase uuids, and a
+ * link that has been through a system which upper-cased it should still resolve
+ * rather than silently miss.
+ */
+export function identifierFromRef(ref) {
+    const match = TRAILING_UUID_RE.exec(ref);
+    return match ? match[0].toLowerCase() : null;
+}
+/** The `urls` shapes a manifest event declares. */
+export function urlPatternsOf(event) {
+    const out = [];
+    for (const tag of event.tags) {
+        if (tag[0] !== 'urls' || !tag[1])
+            continue;
+        const kind = tag[2] ? Number(tag[2]) : undefined;
+        out.push({ pattern: tag[1], ...(Number.isInteger(kind) ? { kind } : {}) });
+    }
+    return out;
+}
+/**
+ * Match a pasted URL against one app's declared shapes.
+ *
+ * **The host and the `<type>` segment are significant; the slug is not.** That
+ * is §7.2 as amended, and it is the whole of the security story here: a
+ * consumer that matched on the trailing uuid alone would resolve any URL from
+ * anywhere as that app's object.
+ *
+ * Returns null for a URL no pattern claims, which is the honest outcome — §7.5
+ * says such a URL renders as a plain link, because it is one.
+ */
+export function matchObjectUrl(url, patterns) {
+    const target = splitUrl(url);
+    if (!target)
+        return null;
+    for (const { pattern, kind } of patterns) {
+        const shape = splitUrl(pattern);
+        if (!shape)
+            continue;
+        if (shape.scheme !== target.scheme || shape.host !== target.host)
+            continue;
+        // The pattern's path up to its final segment: `/issue/` out of
+        // `/issue/<slug>-<d>`. Compared literally and at equal depth, so `/issues`
+        // never matches `/issue/…` and a nested route never matches a shallower one.
+        if (shape.segments.length !== target.segments.length)
+            continue;
+        const prefixMatches = shape.segments
+            .slice(0, -1)
+            .every((segment, i) => segment === target.segments[i]);
+        if (!prefixMatches)
+            continue;
+        const identifier = identifierFromRef(target.segments[target.segments.length - 1] ?? '');
+        if (!identifier)
+            continue;
+        return { identifier, ...(kind === undefined ? {} : { kind }) };
+    }
+    return null;
+}
+/**
+ * Scheme, host and path segments — the whole of the URL this grammar reads.
+ *
+ * Hand-parsed rather than through `new URL()`, which is an ambient global this
+ * package may not reach for: `tsconfig.base.json` sets `types: []` and a `lib`
+ * without DOM on purpose (ADR 0002 §4a), so that a published declaration cannot
+ * name a type one consumer has and another does not. The grammar is three
+ * fields; a parser for it is cheaper than the constraint it would break.
+ *
+ * Only `http` and `https` parse, which is belt-and-braces rather than the load
+ * -bearing rule: a `javascript:` or `data:` URL is already refused for having no
+ * `://` authority, and any other scheme is refused by the scheme comparison
+ * against a declared pattern, since every pattern an app publishes is `https`.
+ * A control confirmed that — relaxing this regex to accept any scheme failed no
+ * test. It stays because the cost is a character class and it makes the
+ * refusal local to the parser rather than a consequence of what apps happen to
+ * declare.
+ */
+function splitUrl(raw) {
+    const match = /^(https?):\/\/([^/?#]+)([^?#]*)/i.exec(raw.trim());
+    if (!match)
+        return null;
+    const [, scheme, host, path] = match;
+    return {
+        scheme: scheme.toLowerCase(),
+        host: host.toLowerCase(),
+        segments: (path ?? '').split('/').filter(Boolean),
+    };
+}
+//# sourceMappingURL=objectUrl.js.map

package/dist/objectUrl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectUrl.js","sourceRoot":"","sources":["../src/objectUrl.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/interop",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "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.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -62,3 +62,21 @@ export {
   ACTION_EFFECTS,
   type UnsignedActionEvent,
 } from './projection.js'
+
+/**
+ * RFC 0.5 §7's URL grammar — how an object is named in an address bar, and how
+ * a pasted link is matched back to one.
+ *
+ * Separate from the projection surface above because it answers a different
+ * question: those resolve an object you already hold, these turn a string
+ * somebody pasted into one you can hold.
+ */
+export {
+  slugify,
+  objectRef,
+  identifierFromRef,
+  urlPatternsOf,
+  matchObjectUrl,
+  type UrlPattern,
+  type MatchedObjectUrl,
+} from './objectUrl.js'

package/src/objectUrl.ts

@@ -0,0 +1,192 @@
+/**
+ * Object URLs — RFC 0.5 §7, accepted 2026-09-03.
+ *
+ *     https://<app>.estiva.app/<type>s              a directory of that kind
+ *     https://<app>.estiva.app/<type>/<slug>-<d>    one object
+ *
+ * **Here rather than in each app** because it is wire-visible: §7.1's whole
+ * argument is that the URL one app puts in the address bar has to be resolvable
+ * by another, which is SPEC §10's test for something the protocol owns. Two
+ * implementations would disagree about what a slug may contain, and the
+ * disagreement would show up as a link that resolves in the app that wrote it
+ * and nowhere else.
+ *
+ * Peek's `src/lib/objectUrl.ts` is where `slugify`, `objectRef` and
+ * `identifierFromRef` were written (PEE-14) and they are moved rather than
+ * rewritten — an extraction that changes behaviour while every test still
+ * passes is the thing to guard against, so Peek's own cases come with them.
+ *
+ * Two properties from §7.2 do all the work:
+ *
+ *   - **The uuid is the whole identity and is never truncated.** A consumer
+ *     resolves `{"#d": ["<uuid>"]}` — one query, no index, and no service that
+ *     can go down and take every published link with it.
+ *   - **The slug is decorative.** Renaming the object changes it and the link
+ *     still resolves, because a reader ignores everything between the `<type>`
+ *     segment and the final uuid.
+ *
+ * That second sentence is the amended one. §7.2 used to say a consumer MUST
+ * ignore *everything* before the final uuid, which contradicted the paragraph
+ * above it and, read literally, resolves `evil.example.com/issue/<uuid>` as a
+ * Ship issue. The host and the `<type>` segment are exactly what select the app
+ * and the kind; only the slug is decoration. `matchObjectUrl` implements the
+ * corrected rule.
+ */
+
+/**
+ * A v4 uuid at the very end of a ref.
+ *
+ * Anchored at the end rather than searched for, because §7.2's rule is
+ * positional: the identity is the tail, and everything before it is a human
+ * label that may itself contain hyphens, digits and hex.
+ */
+const TRAILING_UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Slugs are cut here. Long enough to stay recognisable in a chat client's link
+ * preview, short enough that the uuid is not pushed off the end of a rendered
+ * URL — which is the only thing in the ref that carries meaning.
+ */
+const SLUG_MAX_LENGTH = 60
+
+/**
+ * A title reduced to URL-safe words. Decorative by contract: nothing resolves
+ * through it, so it is free to be lossy — accents folded, punctuation dropped,
+ * runs collapsed.
+ */
+export function slugify(title: string): string {
+  return title
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX_LENGTH)
+    .replace(/-+$/g, '')
+}
+
+/** `<slug>-<identifier>`, or the bare identifier when the title slugs to nothing. */
+export function objectRef(identifier: string, title?: string): string {
+  const slug = title ? slugify(title) : ''
+  return slug ? `${slug}-${identifier}` : identifier
+}
+
+/**
+ * The identity out of a ref, or `null` if it carries none.
+ *
+ * Lowercased on the way out: the relay's `d` values are lowercase uuids, and a
+ * link that has been through a system which upper-cased it should still resolve
+ * rather than silently miss.
+ */
+export function identifierFromRef(ref: string): string | null {
+  const match = TRAILING_UUID_RE.exec(ref)
+  return match ? match[0].toLowerCase() : null
+}
+
+/**
+ * A URL shape an app says it serves — RFC 0.5 §7.5's `urls`, read off the
+ * manifest event the way `web` is.
+ *
+ * `web` is outbound (given an object, build a link); this is inbound (given a
+ * link, recover the object). Usually the same strings, separate fields because
+ * they answer different questions — and because an app that changes its routes
+ * still has to read the links it published under the old ones.
+ */
+export interface UrlPattern {
+  /** e.g. `https://ship.estiva.app/issue/<slug>-<d>` */
+  pattern: string
+  /**
+   * The kind this shape names, when the app said so.
+   *
+   * §7.2 says the kind comes from the path segment — but `/issue/` means 30851
+   * only *to the app serving it*, and a consumer has never heard of "issue".
+   * So an app MAY name the kind alongside the pattern. When it does not, a
+   * consumer falls back to the kinds the manifest declares it handles, which is
+   * sound because no `d` is reused under two kinds — measured across all 280
+   * production records at §7's acceptance.
+   */
+  kind?: number
+}
+
+/** The `urls` shapes a manifest event declares. */
+export function urlPatternsOf(event: { tags: string[][] }): UrlPattern[] {
+  const out: UrlPattern[] = []
+  for (const tag of event.tags) {
+    if (tag[0] !== 'urls' || !tag[1]) continue
+    const kind = tag[2] ? Number(tag[2]) : undefined
+    out.push({ pattern: tag[1], ...(Number.isInteger(kind) ? { kind } : {}) })
+  }
+  return out
+}
+
+/** What a pasted URL turned out to name. */
+export interface MatchedObjectUrl {
+  identifier: string
+  /** Present only when the matched pattern named one. */
+  kind?: number
+}
+
+/**
+ * Match a pasted URL against one app's declared shapes.
+ *
+ * **The host and the `<type>` segment are significant; the slug is not.** That
+ * is §7.2 as amended, and it is the whole of the security story here: a
+ * consumer that matched on the trailing uuid alone would resolve any URL from
+ * anywhere as that app's object.
+ *
+ * Returns null for a URL no pattern claims, which is the honest outcome — §7.5
+ * says such a URL renders as a plain link, because it is one.
+ */
+export function matchObjectUrl(url: string, patterns: UrlPattern[]): MatchedObjectUrl | null {
+  const target = splitUrl(url)
+  if (!target) return null
+
+  for (const { pattern, kind } of patterns) {
+    const shape = splitUrl(pattern)
+    if (!shape) continue
+    if (shape.scheme !== target.scheme || shape.host !== target.host) continue
+
+    // The pattern's path up to its final segment: `/issue/` out of
+    // `/issue/<slug>-<d>`. Compared literally and at equal depth, so `/issues`
+    // never matches `/issue/…` and a nested route never matches a shallower one.
+    if (shape.segments.length !== target.segments.length) continue
+    const prefixMatches = shape.segments
+      .slice(0, -1)
+      .every((segment, i) => segment === target.segments[i])
+    if (!prefixMatches) continue
+
+    const identifier = identifierFromRef(target.segments[target.segments.length - 1] ?? '')
+    if (!identifier) continue
+    return { identifier, ...(kind === undefined ? {} : { kind }) }
+  }
+  return null
+}
+
+/**
+ * Scheme, host and path segments — the whole of the URL this grammar reads.
+ *
+ * Hand-parsed rather than through `new URL()`, which is an ambient global this
+ * package may not reach for: `tsconfig.base.json` sets `types: []` and a `lib`
+ * without DOM on purpose (ADR 0002 §4a), so that a published declaration cannot
+ * name a type one consumer has and another does not. The grammar is three
+ * fields; a parser for it is cheaper than the constraint it would break.
+ *
+ * Only `http` and `https` parse, which is belt-and-braces rather than the load
+ * -bearing rule: a `javascript:` or `data:` URL is already refused for having no
+ * `://` authority, and any other scheme is refused by the scheme comparison
+ * against a declared pattern, since every pattern an app publishes is `https`.
+ * A control confirmed that — relaxing this regex to accept any scheme failed no
+ * test. It stays because the cost is a character class and it makes the
+ * refusal local to the parser rather than a consequence of what apps happen to
+ * declare.
+ */
+function splitUrl(raw: string): { scheme: string; host: string; segments: string[] } | null {
+  const match = /^(https?):\/\/([^/?#]+)([^?#]*)/i.exec(raw.trim())
+  if (!match) return null
+  const [, scheme, host, path] = match
+  return {
+    scheme: scheme.toLowerCase(),
+    host: host.toLowerCase(),
+    segments: (path ?? '').split('/').filter(Boolean),
+  }
+}