@estiva-app/interop 0.55.0 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -839,6 +839,18 @@ export const MOVED_TO_TAG = 'A';
839
839
  * not only the author.
840
840
  */
841
841
  export const ARCHIVED_FIELD = 'archived';
842
+ /**
843
+ * The field, and the root tag seeding it, that holds a file's one-line summary,
844
+ * whatever its kind — SPEC §6.12.
845
+ *
846
+ * Plain text, one or two sentences, beside the title: what a card, a row or a
847
+ * picker shows under it. Changed by a `kind:1851` like the title, last write
848
+ * wins, and a value that is blank after trimming means no summary. Every file
849
+ * kind's `subtitle` reads it ({@link defaultSubtitle}), so no manifest has to.
850
+ *
851
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-files-summary-is-its-own-field.md
852
+ */
853
+ export const SUMMARY_FIELD = 'summary';
842
854
  /**
843
855
  * Where a `ResolvedManifest.address` would name the manifest event, this names
844
856
  * the section of the specification the manifest is built from. Not an address,
@@ -879,7 +891,7 @@ const BARE_FILE_MANIFEST = {
879
891
  // `movedBy` is SPEC §6.7's `parent` field, declared rather than
880
892
  // hard-coded since MAN-1, so a bare file moves by the rule every other
881
893
  // kind does — the move action below sets the same field.
882
- list: { children: { kind: KIND_BARE_FILE, via: 'a', limit: 200, movedBy: 'parent' } },
894
+ list: { children: { kind: KIND_BARE_FILE, via: 'a', limit: 200, movedBy: 'parent', anyParent: true } },
883
895
  },
884
896
  },
885
897
  /*
@@ -959,6 +971,22 @@ const BARE_FILE_MANIFEST = {
959
971
  emits: { kind: 1851, field: 'description' },
960
972
  input: { type: 'string', format: BLOCK_DOCUMENT_FORMAT },
961
973
  },
974
+ /*
975
+ `summarize` sets the file's one-line summary (SPEC §6.12): plain text, so
976
+ its input declares no `format` (§7.3), and a consumer finds it by
977
+ `emits.field`, not by this id. An empty value clears it, the summary the
978
+ file was created with included.
979
+ */
980
+ {
981
+ id: 'summarize',
982
+ label: 'Summary',
983
+ description: "Set this file's summary: one or two sentences of plain text, about 240 characters, shown under its " +
984
+ 'title wherever it is met in one line. A change event, so anyone in the Folder may; an empty value clears it.',
985
+ effect: 'writes',
986
+ appliesTo: [String(KIND_BARE_FILE)],
987
+ emits: { kind: 1851, field: SUMMARY_FIELD },
988
+ input: { type: 'string' },
989
+ },
962
990
  /*
963
991
  `move` is the `parent` field SPEC §6.7 already defines, declared so a
964
992
  consumer draws the control from here as it draws Rename (FOL-4). The value
@@ -1023,6 +1051,8 @@ function bareFileManifest() {
1023
1051
  * What a Folder's built-in actions are declared by — SPEC §3.2, as
1024
1052
  * {@link BARE_FILE_MANIFEST_ADDRESS} is for the bare file. The
1025
1053
  * `declaredBy.address` of an action no app declared.
1054
+ *
1055
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/folders-belong-to-the-protocol.md
1026
1056
  */
1027
1057
  export const FOLDER_ACTIONS_ADDRESS = 'spec:3.2';
1028
1058
  /**
@@ -1053,12 +1083,18 @@ const FOLDER_CREATOR = {
1053
1083
  {
1054
1084
  id: 'create-file',
1055
1085
  label: 'New file',
1056
- description: 'Put a new file in this Folder: a title, and nothing else yet. Everyone who can read the Folder can read ' +
1086
+ description: 'Put a new file in this Folder: a title and, if you have one, a short summary. Everyone who can read the Folder can read ' +
1057
1087
  'it, and the Folder lists it straight away. The app opening files calls it by its own word — Peek says topic.',
1058
1088
  effect: 'writes',
1059
1089
  appliesTo: String(KIND_CHANNEL_METADATA),
1060
1090
  emits: { kind: KIND_BARE_FILE, listed: true },
1061
- input: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
1091
+ // `summary` is the root tag that seeds the new file's summary (SPEC
1092
+ // §3.2, §6.12); left empty, it is omitted (§7.3).
1093
+ input: {
1094
+ type: 'object',
1095
+ properties: { title: { type: 'string' }, [SUMMARY_FIELD]: { type: 'string' } },
1096
+ required: ['title'],
1097
+ },
1062
1098
  },
1063
1099
  ],
1064
1100
  },
@@ -1073,6 +1109,8 @@ const FOLDER_CREATOR = {
1073
1109
  * runtime's, so a published manifest still cannot change how a bare file
1074
1110
  * behaves; it can only say what it is called where it opens. A comment takes
1075
1111
  * the name (it opens in the same app) and not the noun, which is the file's.
1112
+ *
1113
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/a-file-is-labelled-by-its-type-not-its-app.md
1076
1114
  */
1077
1115
  function bareFileOpenedBy(opener, template) {
1078
1116
  const name = wordOf(opener.name) ?? BARE_FILE_MANIFEST.name;
@@ -1518,6 +1556,8 @@ import { contentFormatOf } from '@estiva-app/protocol';
1518
1556
  * and a consumer reads `slots.body` to find it.
1519
1557
  */
1520
1558
  export const BODY_SLOT = 'body';
1559
+ /** The slot that is a file's summary, one line of plain text (SPEC §7.2). */
1560
+ const SUBTITLE_SLOT = 'subtitle';
1521
1561
  /**
1522
1562
  * Does this change sit in the Folder its target is filed in — SPEC §6.2.
1523
1563
  *
@@ -1581,6 +1621,10 @@ function foldChanges(changes, rule, root) {
1581
1621
  const value = tagValue(change, rule.valueTag);
1582
1622
  if (!field || value === undefined)
1583
1623
  continue; // a partial change sets nothing
1624
+ // A summary is new, so it takes neither of §6.2's exceptions: a change the
1625
+ // reader cannot check against the root's Folder is not read (SPEC §6.12).
1626
+ if (field === SUMMARY_FIELD && !folders)
1627
+ continue;
1584
1628
  // The format travels with the *winning* change, not with the object. SPEC
1585
1629
  // §13.4: "an app MUST read the tag from the event it took the value from,
1586
1630
  // never from the object's root" — a description created as marker text and
@@ -2007,7 +2051,20 @@ function resolveSlot(spec, root, folded, manifest, name) {
2007
2051
  const source = rawSlotValue(spec, root, folded, name === BODY_SLOT);
2008
2052
  if (source === undefined || source.value === '')
2009
2053
  return null;
2010
- const raw = source.value;
2054
+ let raw = source.value;
2055
+ /*
2056
+ `subtitle` is plain text on one line (SPEC §7.2, §6.12): line breaks fold to
2057
+ spaces, and a value that is blank once trimmed is no subtitle — a summary
2058
+ cleared with " " reads as cleared, and the seed does not show through it.
2059
+ Left to each consumer, `slots.subtitle &&` drew a blank one as an empty line
2060
+ (Peek's ForeignObjectWidget). A body-shaped value declared into the slot is
2061
+ left alone; the truncation guard below is what speaks to that.
2062
+ */
2063
+ if (name === SUBTITLE_SLOT && source.format !== 'blocks' && source.format !== 'unknown') {
2064
+ raw = raw.replace(/\s+/g, ' ').trim();
2065
+ if (raw === '')
2066
+ return null;
2067
+ }
2011
2068
  /*
2012
2069
  PRO-8's rule, now enforceable rather than only written down.
2013
2070
 
@@ -2045,6 +2102,65 @@ function resolveSlot(spec, root, folded, manifest, name) {
2045
2102
  ...(source.format ? { format: source.format } : {}),
2046
2103
  };
2047
2104
  }
2105
+ /*
2106
+ `truncate` is the clamp SPEC §6.12 makes a reader's job: the relay does not
2107
+ hold a writer to about 240 characters, and with no manifest declaring the
2108
+ slot nothing else would cut a 1,000-character summary down to a line. A
2109
+ consumer still clamps it to its own room; this is the backstop.
2110
+ */
2111
+ const SUMMARY_TRUNCATE = 280;
2112
+ const SUMMARY_SUBTITLE = { tag: SUMMARY_FIELD, fold: SUMMARY_FIELD, truncate: SUMMARY_TRUNCATE };
2113
+ const FOLDER_SUBTITLE = { tag: 'about' };
2114
+ /**
2115
+ * Where a kind's `subtitle` comes from whatever its manifest says, or
2116
+ * `undefined` where the manifest decides — SPEC §7.2, §6.12, §3.2.
2117
+ *
2118
+ * - **A Folder** (`kind:39000`): the `about` of its channel record, NIP-29's
2119
+ * one-liner. A `summary` change aimed at one is not read.
2120
+ * - **Every other addressable kind is a file**, and its subtitle is its
2121
+ * summary: the `summary` fold over the root tag of that name. Built in, so an
2122
+ * app's files — an outside company's included — show their summary on every
2123
+ * card with nothing in its manifest, and no manifest can point the line at
2124
+ * another field (Miky, 2026-10-15, kickoff).
2125
+ * - NIP-29's other `39001`–`39009` records, and regular events (a message, a
2126
+ * comment), keep what their manifest declares.
2127
+ */
2128
+ function defaultSubtitle(kind) {
2129
+ if (kind === KIND_CHANNEL_METADATA)
2130
+ return FOLDER_SUBTITLE;
2131
+ if (kind >= 39000 && kind <= 39009)
2132
+ return undefined;
2133
+ return isAddressableKind(kind) ? SUMMARY_SUBTITLE : undefined;
2134
+ }
2135
+ /**
2136
+ * A projection's slots with `subtitle` taken from {@link defaultSubtitle}.
2137
+ *
2138
+ * A declaration naming the same source keeps its `label` and a `truncate`
2139
+ * tighter than the built-in one (Peek's Folder projection truncates `about` at
2140
+ * 120); one naming any other source, or an array, is replaced.
2141
+ */
2142
+ function withDefaultSubtitle(slots, kind) {
2143
+ const builtIn = defaultSubtitle(kind);
2144
+ if (!builtIn)
2145
+ return slots;
2146
+ const declared = slots[SUBTITLE_SLOT];
2147
+ const same = declared !== undefined &&
2148
+ !Array.isArray(declared) &&
2149
+ declared.tag === builtIn.tag &&
2150
+ declared.fold === builtIn.fold &&
2151
+ declared.field === undefined &&
2152
+ declared.default === undefined &&
2153
+ declared.map === undefined &&
2154
+ declared.as === undefined &&
2155
+ declared.children === undefined;
2156
+ if (!same)
2157
+ return { ...slots, [SUBTITLE_SLOT]: builtIn };
2158
+ // Same source: its `label` and a tighter `truncate` stand, never a looser one.
2159
+ const truncate = declared.truncate === undefined || builtIn.truncate === undefined
2160
+ ? (declared.truncate ?? builtIn.truncate)
2161
+ : Math.min(declared.truncate, builtIn.truncate);
2162
+ return { ...slots, [SUBTITLE_SLOT]: { ...builtIn, label: declared.label, truncate } };
2163
+ }
2048
2164
  /**
2049
2165
  * Every slot a projection declares, resolved.
2050
2166
  *
@@ -2055,7 +2171,7 @@ function resolveSlot(spec, root, folded, manifest, name) {
2055
2171
  function resolveSlots(projection, root, folded, manifest) {
2056
2172
  const slots = {};
2057
2173
  const meta = [];
2058
- for (const [name, spec] of Object.entries(projection.slots)) {
2174
+ for (const [name, spec] of Object.entries(withDefaultSubtitle(projection.slots, root.kind))) {
2059
2175
  if (Array.isArray(spec)) {
2060
2176
  for (const one of spec) {
2061
2177
  // An array spec collects into `meta`, so the name it was declared under
@@ -2094,7 +2210,9 @@ function buildObject(args) {
2094
2210
  * nothing.
2095
2211
  */
2096
2212
  const held = {};
2097
- for (const spec of Object.values(projection.slots).flat()) {
2213
+ // The built-in subtitle too, or a summary seeded at creation shows on the
2214
+ // card while `summarize` offers a blank to edit (SPEC §6.12).
2215
+ for (const spec of Object.values(withDefaultSubtitle(projection.slots, root.kind)).flat()) {
2098
2216
  // `tag` may name several spellings (see `SlotSpec`); the field this slot
2099
2217
  // *is* keyed on is the first, which is the one the app writes today. The
2100
2218
  // rest are only there to keep older records rendering.
@@ -2947,8 +3065,9 @@ function parentRefOf(manifest, kind, root, folded = {}) {
2947
3065
  return prefix.test(moved.value) ? moved.value : undefined;
2948
3066
  }
2949
3067
  }
2950
- if (kind === KIND_BARE_FILE) {
2951
- return root.tags.find((t) => t[0] === 'a' && t[1] && /^\d+:[0-9a-f]{64}:/.test(t[1]))?.[1];
3068
+ const own = ownParentTagOf(manifest, kind);
3069
+ if (own) {
3070
+ return root.tags.find((t) => t[0] === own && t[1] && /^\d+:[0-9a-f]{64}:/.test(t[1]))?.[1];
2952
3071
  }
2953
3072
  for (const [parentKind, projection] of Object.entries(manifest.projections ?? {})) {
2954
3073
  const children = declaredChildSpec(projection);
@@ -2975,8 +3094,9 @@ function parentRefOf(manifest, kind, root, folded = {}) {
2975
3094
  * parent it names — SPEC §7.2's `movedBy`, read off whichever projection lists
2976
3095
  * `kind` as its children (MAN-1).
2977
3096
  *
2978
- * `parentKind` is absent for a bare file: §6.7 lets one sit under a file of any
2979
- * kind, so its own list naming bare files is not a limit on where it may go.
3097
+ * `parentKind` is absent for a bare file and for any kind a list declares with
3098
+ * `anyParent` (a document): each may sit under a file of any kind (§6.7), so
3099
+ * the list naming it is not a limit on where it may go.
2980
3100
  * Absent too for `match: 'identifier'`, where `movedBy` is ignored because a
2981
3101
  * move's value is an address and that list compares identifiers.
2982
3102
  */
@@ -2985,7 +3105,28 @@ function movedByOf(manifest, kind) {
2985
3105
  const children = declaredChildSpec(projection);
2986
3106
  if (!children || children.kind !== kind || !children.movedBy || children.match === 'identifier')
2987
3107
  continue;
2988
- return kind === KIND_BARE_FILE ? { field: children.movedBy } : { field: children.movedBy, parentKind: Number(parentKind) };
3108
+ // Any list declaring `anyParent` for the kind lifts the limit, so this and
3109
+ // `ownParentTagOf` never disagree about where the kind may sit.
3110
+ return ownParentTagOf(manifest, kind) !== undefined
3111
+ ? { field: children.movedBy }
3112
+ : { field: children.movedBy, parentKind: Number(parentKind) };
3113
+ }
3114
+ return undefined;
3115
+ }
3116
+ /**
3117
+ * The tag a `kind` object names its own parent with, of any kind — `a` on a
3118
+ * bare file (SPEC §6.7), and the `via` of any list declaring the kind with
3119
+ * `anyParent` (a document's, 2026-10-14). Undefined for every other kind,
3120
+ * whose parent is found from the parent's declared list instead.
3121
+ */
3122
+ function ownParentTagOf(manifest, kind) {
3123
+ if (kind === KIND_BARE_FILE)
3124
+ return 'a';
3125
+ for (const projection of Object.values(manifest.projections ?? {})) {
3126
+ const children = declaredChildSpec(projection);
3127
+ // Strictly `true`: nothing validates a published manifest, and "false" is truthy.
3128
+ if (children?.kind === kind && children.anyParent === true && children.match !== 'identifier')
3129
+ return children.via;
2989
3130
  }
2990
3131
  return undefined;
2991
3132
  }
@@ -4279,6 +4420,8 @@ const nameOf = (event) => (event ? tagValue(event, 'name') : undefined);
4279
4420
  /**
4280
4421
  * The owners and admins a `kind:39001` lists — kept only when the channel's own
4281
4422
  * signer, the relay, signed it: anybody can publish an event of that shape.
4423
+ *
4424
+ * why: https://github.com/estiva-app/estiva-docs/blob/main/decisions/only-owners-and-admins-rename-or-archive-a-folder.md
4282
4425
  */
4283
4426
  function folderAdminsOf(admins, channel) {
4284
4427
  if (!admins || !channel || admins.pubkey !== channel.pubkey)