@estiva-app/interop 0.9.1 → 0.10.1

package/CHANGELOG.md

@@ -6,6 +6,68 @@ 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.1 — 2026-09-03
+
+**`matchObjectUrl` matched no fragment route at all.** The parser's path capture
+stopped at the `#`, so `https://ship.estiva.app/#/issue/<uuid>` reduced to no
+segments and matched nothing — including patterns declaring exactly that shape.
+
+That is not a corner. Ship served fragment routes until SHI-16 and declares them
+still, so that links already sitting in other people's messages resolve rather
+than rendering as plain text for ever. A consumer on 0.10.0 would have silently
+failed every one of them.
+
+Found by a production probe before any consumer was built on it, which is the
+argument for probing the mechanism rather than the fixture.
+
+- Path and fragment segments are concatenated rather than swapped, because an
+  app may be served under a sub-path *and* use a fragment — Ship's own dev URL
+  is `localhost:5190/ship/#/…`, where both halves carry meaning.
+- A fragment route and a path route stay distinct shapes. Collapsing them would
+  let a pattern for `/issue/<slug>-<d>` claim `/#/issue/<d>`, and an app that
+  means different things by the two would resolve the wrong object.
+
+## 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

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,CAyB3F"}

package/dist/objectUrl.js

@@ -0,0 +1,181 @@
+/**
+ * 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;
+        // A fragment route and a path route are different shapes, not one.
+        if (shape.fragmented !== target.fragmented)
+            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, fragment] = match;
+    /*
+      A fragment route counts as path.
+  
+      Ship served `#/issue/<d>` until SHI-16 and still declares those shapes, so
+      that links already sitting in other people's messages resolve rather than
+      rendering as plain text for ever. A parser that stopped at the `#` — this
+      one did — matched none of them, which a production probe caught before any
+      consumer was built on it.
+  
+      Segments from the path and the fragment are concatenated rather than
+      swapped, because an app may be served under a sub-path *and* use a
+      fragment: Ship's own dev URL is `localhost:5190/ship/#/…`, where both
+      halves carry meaning.
+  
+      `fragmented` is kept so the two do not collapse into each other. Without it
+      a pattern for `/issue/<slug>-<d>` would also claim `/#/issue/<d>`, and an
+      app that means different things by the two would resolve the wrong object.
+    */
+    const fragmentPath = fragment && fragment.startsWith('/') ? fragment : '';
+    return {
+        scheme: scheme.toLowerCase(),
+        host: host.toLowerCase(),
+        segments: [...(path ?? '').split('/'), ...fragmentPath.split('/')].filter(Boolean),
+        fragmented: fragmentPath !== '',
+    };
+}
+//# 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.1",
+  "version": "0.10.1",
   "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,215 @@
+/**
+ * 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
+    // A fragment route and a path route are different shapes, not one.
+    if (shape.fragmented !== target.fragmented) 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[]; fragmented: boolean } | null {
+  const match = /^(https?):\/\/([^/?#]+)([^?#]*)(?:\?[^#]*)?(?:#(.*))?$/i.exec(raw.trim())
+  if (!match) return null
+  const [, scheme, host, path, fragment] = match
+
+  /*
+    A fragment route counts as path.
+
+    Ship served `#/issue/<d>` until SHI-16 and still declares those shapes, so
+    that links already sitting in other people's messages resolve rather than
+    rendering as plain text for ever. A parser that stopped at the `#` — this
+    one did — matched none of them, which a production probe caught before any
+    consumer was built on it.
+
+    Segments from the path and the fragment are concatenated rather than
+    swapped, because an app may be served under a sub-path *and* use a
+    fragment: Ship's own dev URL is `localhost:5190/ship/#/…`, where both
+    halves carry meaning.
+
+    `fragmented` is kept so the two do not collapse into each other. Without it
+    a pattern for `/issue/<slug>-<d>` would also claim `/#/issue/<d>`, and an
+    app that means different things by the two would resolve the wrong object.
+  */
+  const fragmentPath = fragment && fragment.startsWith('/') ? fragment : ''
+  return {
+    scheme: scheme.toLowerCase(),
+    host: host.toLowerCase(),
+    segments: [...(path ?? '').split('/'), ...fragmentPath.split('/')].filter(Boolean),
+    fragmented: fragmentPath !== '',
+  }
+}