@minca/core 0.1.13 → 0.1.15

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.
Files changed (148) hide show
  1. package/README.md +2 -2
  2. package/dist/files/space-files.d.ts +15 -3
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +225 -37
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/index.d.ts +1 -1
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +1 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/network/introductions.d.ts +20 -7
  11. package/dist/network/introductions.d.ts.map +1 -1
  12. package/dist/network/introductions.js +9 -6
  13. package/dist/network/introductions.js.map +1 -1
  14. package/dist/network/mesh.d.ts.map +1 -1
  15. package/dist/network/mesh.js +88 -20
  16. package/dist/network/mesh.js.map +1 -1
  17. package/dist/network/relay-minca.d.ts +12 -1
  18. package/dist/network/relay-minca.d.ts.map +1 -1
  19. package/dist/network/relay-minca.js +14 -6
  20. package/dist/network/relay-minca.js.map +1 -1
  21. package/dist/network/relay-nostr.d.ts +14 -3
  22. package/dist/network/relay-nostr.d.ts.map +1 -1
  23. package/dist/network/relay-nostr.js +11 -9
  24. package/dist/network/relay-nostr.js.map +1 -1
  25. package/dist/network/relays.d.ts +26 -17
  26. package/dist/network/relays.d.ts.map +1 -1
  27. package/dist/network/relays.js +21 -28
  28. package/dist/network/relays.js.map +1 -1
  29. package/dist/network/rendezvous.d.ts +1 -1
  30. package/dist/network/rendezvous.d.ts.map +1 -1
  31. package/dist/network/rendezvous.js +2 -2
  32. package/dist/network/rendezvous.js.map +1 -1
  33. package/dist/node/actions.d.ts.map +1 -1
  34. package/dist/node/actions.js +54 -2
  35. package/dist/node/actions.js.map +1 -1
  36. package/dist/node/node.d.ts.map +1 -1
  37. package/dist/node/node.js +7 -7
  38. package/dist/node/node.js.map +1 -1
  39. package/dist/node/space-runtime.d.ts +1 -1
  40. package/dist/node/space-runtime.d.ts.map +1 -1
  41. package/dist/node/space-runtime.js +17 -5
  42. package/dist/node/space-runtime.js.map +1 -1
  43. package/dist/node/types.d.ts +4 -3
  44. package/dist/node/types.d.ts.map +1 -1
  45. package/dist/schema/collection-def.d.ts.map +1 -1
  46. package/dist/schema/collection-def.js +16 -5
  47. package/dist/schema/collection-def.js.map +1 -1
  48. package/dist/schemas/automations.d.ts +8 -0
  49. package/dist/schemas/automations.d.ts.map +1 -1
  50. package/dist/schemas/blueprints.d.ts +33 -0
  51. package/dist/schemas/blueprints.d.ts.map +1 -1
  52. package/dist/schemas/blueprints.js +63 -0
  53. package/dist/schemas/blueprints.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +12 -0
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/fragments.d.ts +22 -2
  57. package/dist/schemas/fragments.d.ts.map +1 -1
  58. package/dist/schemas/fragments.js +20 -12
  59. package/dist/schemas/fragments.js.map +1 -1
  60. package/dist/schemas/library/annotations.d.ts +30 -0
  61. package/dist/schemas/library/annotations.d.ts.map +1 -1
  62. package/dist/schemas/library/annotations.js +1 -0
  63. package/dist/schemas/library/annotations.js.map +1 -1
  64. package/dist/schemas/library/community.d.ts +28 -0
  65. package/dist/schemas/library/community.d.ts.map +1 -1
  66. package/dist/schemas/library/life.d.ts +62 -2
  67. package/dist/schemas/library/life.d.ts.map +1 -1
  68. package/dist/schemas/library/media.d.ts +36 -0
  69. package/dist/schemas/library/media.d.ts.map +1 -1
  70. package/dist/schemas/library/money.d.ts +74 -2
  71. package/dist/schemas/library/money.d.ts.map +1 -1
  72. package/dist/schemas/library/planning.d.ts +56 -0
  73. package/dist/schemas/library/planning.d.ts.map +1 -1
  74. package/dist/schemas/library/publishing.d.ts +80 -4
  75. package/dist/schemas/library/publishing.d.ts.map +1 -1
  76. package/dist/schemas/library/social.d.ts +44 -0
  77. package/dist/schemas/library/social.d.ts.map +1 -1
  78. package/docs/README.md +2 -2
  79. package/docs/actions.md +83 -56
  80. package/docs/blueprints-and-guides.md +41 -13
  81. package/docs/building-an-app.md +4 -4
  82. package/docs/collections.md +31 -3
  83. package/docs/node.md +15 -13
  84. package/docs/proposing-collections.md +42 -0
  85. package/docs/standard-library.md +26 -25
  86. package/docs/storage.md +33 -10
  87. package/package.json +2 -21
  88. package/dist/calls/calls.d.ts +0 -140
  89. package/dist/calls/calls.d.ts.map +0 -1
  90. package/dist/calls/calls.js +0 -861
  91. package/dist/calls/calls.js.map +0 -1
  92. package/dist/calls/index.d.ts +0 -4
  93. package/dist/calls/index.d.ts.map +0 -1
  94. package/dist/calls/index.js +0 -3
  95. package/dist/calls/index.js.map +0 -1
  96. package/dist/react/context.d.ts +0 -81
  97. package/dist/react/context.d.ts.map +0 -1
  98. package/dist/react/context.js +0 -97
  99. package/dist/react/context.js.map +0 -1
  100. package/dist/react/follow.d.ts +0 -11
  101. package/dist/react/follow.d.ts.map +0 -1
  102. package/dist/react/follow.js +0 -7
  103. package/dist/react/follow.js.map +0 -1
  104. package/dist/react/index.d.ts +0 -44
  105. package/dist/react/index.d.ts.map +0 -1
  106. package/dist/react/index.js +0 -40
  107. package/dist/react/index.js.map +0 -1
  108. package/dist/react/minca-auth.d.ts +0 -19
  109. package/dist/react/minca-auth.d.ts.map +0 -1
  110. package/dist/react/minca-auth.js +0 -36
  111. package/dist/react/minca-auth.js.map +0 -1
  112. package/dist/react/use-calls.d.ts +0 -21
  113. package/dist/react/use-calls.d.ts.map +0 -1
  114. package/dist/react/use-calls.js +0 -39
  115. package/dist/react/use-calls.js.map +0 -1
  116. package/dist/react/use-invite-link.d.ts +0 -24
  117. package/dist/react/use-invite-link.d.ts.map +0 -1
  118. package/dist/react/use-invite-link.js +0 -62
  119. package/dist/react/use-invite-link.js.map +0 -1
  120. package/dist/react/use-live.d.ts +0 -16
  121. package/dist/react/use-live.d.ts.map +0 -1
  122. package/dist/react/use-live.js +0 -56
  123. package/dist/react/use-live.js.map +0 -1
  124. package/dist/react/use-my-name.d.ts +0 -12
  125. package/dist/react/use-my-name.d.ts.map +0 -1
  126. package/dist/react/use-my-name.js +0 -38
  127. package/dist/react/use-my-name.js.map +0 -1
  128. package/dist/react/use-names.d.ts +0 -7
  129. package/dist/react/use-names.d.ts.map +0 -1
  130. package/dist/react/use-names.js +0 -13
  131. package/dist/react/use-names.js.map +0 -1
  132. package/dist/react/use-network.d.ts +0 -9
  133. package/dist/react/use-network.d.ts.map +0 -1
  134. package/dist/react/use-network.js +0 -33
  135. package/dist/react/use-network.js.map +0 -1
  136. package/dist/react/use-query.d.ts +0 -14
  137. package/dist/react/use-query.d.ts.map +0 -1
  138. package/dist/react/use-query.js +0 -26
  139. package/dist/react/use-query.js.map +0 -1
  140. package/dist/react/use-space.d.ts +0 -29
  141. package/dist/react/use-space.d.ts.map +0 -1
  142. package/dist/react/use-space.js +0 -57
  143. package/dist/react/use-space.js.map +0 -1
  144. package/dist/react/use-spaces.d.ts +0 -29
  145. package/dist/react/use-spaces.d.ts.map +0 -1
  146. package/dist/react/use-spaces.js +0 -78
  147. package/dist/react/use-spaces.js.map +0 -1
  148. package/docs/calls.md +0 -189
package/docs/node.md CHANGED
@@ -239,13 +239,13 @@ node makes a key for this run as it would without a source.
239
239
  write fails until the page reloads, since signing on would fork the line
240
240
  and withdraw what the key wrote. A slot whose connection the browser
241
241
  closed opens again only while it still holds the key.
242
- - The CLI keeps them outside its home, in `<local>/writers/slot-<n>/` (`localPath` in `packages/cli/src/home.ts`, [sync and storage](storage.md#data-folders)): the key as
242
+ - The CLI keeps them outside its home, in `<local>/writer-keys/slot-<n>/` (`localPath` in `packages/cli/src/home.ts`, [sync and storage](storage.md#data-folders)): the key as
243
243
  JWK in an envelope (spec 01 §9.1) under the account's local key, with label
244
244
  `minca/writer-key/v1` and bound `{ did: <account DID>, slot: <n> }`
245
245
  (`key.sealed`, mode 600), so a copy of the files can't sign, and a key file
246
246
  moved to another slot or account is refused rather than used; its places in
247
- `heads/`; and a `lock` file naming the process that holds it, taken over
248
- once that process is gone.
247
+ `heads/`; and numbered `lock.<n>` files naming the process that holds the
248
+ highest, taken over once that process is gone.
249
249
 
250
250
  _Source: `packages/core/src/node/writer-keys.ts` (`browserWriterKeys`), `packages/core/src/node/writers.ts` (`createWriters`), `packages/core/src/node/node.ts` (`createNode`, `revokeSelf`), `packages/core/src/node/stores.ts` (`writerKeysFor`), `packages/core/src/node/worker.ts` (`withWriterKey`), `packages/cli/src/writer-keys.ts` (`fileWriterKeys`), `packages/cli/src/home.ts` (`unlock`, `nodeFor`). Tests: `packages/core/tests/writer-logs.test.ts` ("a writer key that outlives the node"), `packages/cli/tests/writer-keys.test.ts` ("a key file moved to another slot, or to another account, does not open")._
251
251
 
@@ -616,7 +616,7 @@ successors, mine, heads, key, relays, keepers, copies, forks, flagged }`
616
616
  accepting also need whole-account access.
617
617
  - `node.carriers`, `node.hosting`, `node.notifications` — [carriers and hosting](#carriers-hosting-and-notifications), [spec 06 §4](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
618
618
  - `node.iceServers()` — the configured ICE servers plus TURN servers a relay
619
- offers ([the network](#the-network)); what [calls](calls.md#connections) use.
619
+ offers ([the network](#the-network)); what [calls](../../calls/README.md#connections) use.
620
620
  - `node.network` — `status()`: each relay's state (open, or waiting to redial,
621
621
  when and why), the connections open and those still being made, and whether
622
622
  a relay offered TURN; `reconnect()` redials a waiting relay now
@@ -655,8 +655,9 @@ says hello back in a room at most once every 10 s; one due sooner waits
655
655
  for the 10 s, once for everyone who said hello meanwhile. Each socket
656
656
  sends at most 20 messages a second, in bursts of 40, and queues the rest. A
657
657
  connection attempt that times out is retried on the peer's next hello. `requestIce`
658
- asks every connected relay for TURN. Each WebRTC offer or answer waits for
659
- ICE gathering to finish, or 2 s, and carries what it found.
658
+ asks every connected relay whose kind can hand out TURN passwords. Each WebRTC
659
+ offer or answer waits for ICE gathering to finish, or 2 s, and carries what it
660
+ found.
660
661
 
661
662
  **Kinds of relay** (spec 04 §1.2). `network.relays` may mix kinds:
662
663
  `['wss://minca.fly.dev', 'nostr+wss://relay.damus.io']`. A relay of a kind
@@ -684,7 +685,7 @@ so the usual sync keeps the two level.
684
685
  **The mesh** (spec 04 §7). Admission raises `peer-connected` for the room. A
685
686
  newly opened connection that no room takes up within 10 s is closed. A
686
687
  connection attempt is given 20 s, doubling with each failed attempt at the
687
- same peer up to 5 min. The node remembers the last 512 relayed-signal ids.
688
+ same peer up to 5 min. The node remembers the last 512 relayed signals it passed on, by their signatures.
688
689
  When a node that must prove read access holds no read key, the handshake
689
690
  throws and the room times out.
690
691
 
@@ -695,8 +696,8 @@ configured servers plus the TURN servers relays offered, the latter only while
695
696
  `expiresAt` is in the future. `node.iceServers()` returns the same list for
696
697
  the application's own connections (a call's). Before answering it refreshes:
697
698
  if any relay is connected and the TURN passwords held are missing or expire
698
- within 10 minutes, and it has not asked in the last 10 minutes, it sends `ice`
699
- to every connected relay and waits up to 1.5 s for an answer (relays without
699
+ within 10 minutes, and it has not asked in the last 10 minutes, it asks every
700
+ connected relay that can and waits up to 1.5 s for an answer (relays without
700
701
  TURN never answer), then returns what it has. A node with no relays returns
701
702
  the configured servers.
702
703
 
@@ -1036,7 +1037,7 @@ _Source: `packages/core/src/node/node.ts` (`keepSpaceHosts`, `askSpaceHost`, `ho
1036
1037
 
1037
1038
  ## Client conveniences
1038
1039
 
1039
- These are not protocol; another client may draw sign-in and [calls](calls.md) however it
1040
+ These are not protocol; another client may draw sign-in and [calls](../../calls/README.md) however it
1040
1041
  likes.
1041
1042
 
1042
1043
  - **`<minca-auth>`** draws the flow of [sign-in](sign-in.md) into its own light DOM (so password
@@ -1046,11 +1047,12 @@ likes.
1046
1047
  `element.auth = createMincaAuth(…)`. It sizes to its container, so it fits a
1047
1048
  page, a modal or a side panel, and draws nothing once someone is in. Colours,
1048
1049
  font and radius are custom properties (`--minca-accent`, `--minca-font`, …).
1049
- - **React** (`@minca/core/react`): `MincaProvider`, `useMinca`,
1050
+ - **React** (`@minca/react`): `MincaProvider`, `useMinca`,
1050
1051
  `useAuth`, `useSession`, `useConnection`, `useAccount`, `useNode`,
1051
1052
  `<MincaAuth>`, `useQuery`, `useLive`, `useSpaces`,
1052
1053
  `useHoldSpace` (holds a space while mounted, releasing it a few seconds late),
1053
1054
  `useRecord`, `useLinked`, `useCollections`, `useProfiles`, `useAccess`,
1054
- `useSpaceStatus`, `useCan`, `CallsProvider`, `useCalls`.
1055
+ `useSpaceStatus`, `useCan`. Calls' `CallsProvider` and `useCalls` are in
1056
+ `@minca/calls/react`.
1055
1057
 
1056
- _Source: `packages/core/src/elements/minca-auth.ts`, `packages/core/src/react/`. Tests: none._
1058
+ _Source: `packages/core/src/elements/minca-auth.ts`, `packages/react/src/`. Tests: none._
@@ -44,6 +44,48 @@ Through `collections_propose`, a standard collection may be given by name
44
44
  (`"std.task"`): `standardCollections` puts the library's definition in its
45
45
  place.
46
46
 
47
+ ## Trying a contract before proposing it
48
+
49
+ Anyone in a space can write records directly, not only through the app that
50
+ proposed a collection, so an app's own checks stop nobody. What records must
51
+ keep to for the app to mean anything (whose turn it is, a legal move, a
52
+ balance) belongs in the collection's [contract](collections.md#contracts),
53
+ which every reader judges.
54
+
55
+ A contract written wrong refuses fair moves, or lets a cheat count, and
56
+ nothing shows it until someone plays. So `collections_propose` takes
57
+ `examples`: versions it runs through their collection's schema and contract
58
+ before writing anything, so the proposer sees a mistake first.
59
+
60
+ ```json
61
+ "examples": [
62
+ { "collection": "app.counter", "body": { "n": 0 }, "expect": "pass" },
63
+ { "collection": "app.counter", "prev": { "body": { "n": 4 } }, "body": { "n": 5 }, "expect": "pass" },
64
+ { "collection": "app.counter", "prev": { "body": { "n": 4 } }, "body": { "n": 9 }, "expect": "fail" },
65
+ { "collection": "app.counter", "prev": { "body": { "n": 4 }, "author": "did:key:z…" }, "body": { "n": 5 }, "author": "did:key:z…", "expect": "pass" }
66
+ ]
67
+ ```
68
+
69
+ - `author` is an account DID, the proposer's when left out. `prev` is the
70
+ version before, `{ body, author?, links? }`, for a contract that reads
71
+ `prev`; its author is this one's unless it names another, so turn-taking
72
+ is tried by naming both. `creator`, who wrote the first version, is the
73
+ version before's author, or this one's, unless given. Without `prev` the
74
+ example is a first version.
75
+ - An example that should count must fit its collection's schema too.
76
+ - If any example comes out other than expected, nothing is proposed, and the
77
+ error says which and why.
78
+ - A collection with a contract that no example names is still proposed, with
79
+ a warning saying so. The warning goes to the proposer only: the person
80
+ applying the blueprint sees the contract's conditions, not whether anyone
81
+ tried them.
82
+ - What examples don't try: rules (`onePer`, `fixed`, `final`), who may write,
83
+ and a contract's `line`. `member(did)` asks the space as it is now, not as
84
+ of what the version saw. A cited version can't be given, so an example
85
+ whose contract cites one never counts as `pass`.
86
+
87
+ _Source: `packages/core/src/schemas/blueprints.ts` (`tryContracts`), `packages/core/src/node/actions.ts` (`collections_propose`). Tests: `packages/core/tests/contracts.test.ts` ("checks: tried before they are proposed")._
88
+
47
89
  ## Saying how they are meant to be used
48
90
 
49
91
  A definition can't say "write one rota for each week, and say in it who does
@@ -90,18 +90,19 @@ keep the library small enough to choose from, and each choice obvious:
90
90
  out in each definition, built by the library's `fragments` so they are
91
91
  identical everywhere:
92
92
 
93
- | Fragment | Shape |
94
- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
- | `when` | string 10–64: RFC 3339 date-time (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
96
- | `day` | string of 10: `YYYY-MM-DD` |
97
- | `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
98
- | DID | string 1–256: an account DID (built by `person`) |
99
- | `money` | `{ amount, currency }`, both required: `amount` a decimal string 1–32 (`"12.50"`), never a number; `currency` ISO 4217, 3 characters |
100
- | `address` | `{ street, locality, region, postcode, country }`, each optional; `country` ISO 3166-1 alpha-2 |
101
- | `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional; `lat` −90–90, `lon` −180–180, WGS 84; `cells` string 1–12[] (≤ 8), the geohash cells of `lat` and `lon` (see Places and areas) |
102
- | `blob` | `{ hash, size, mime, name?, key?, salt? }`: what `records.addFile` gives: `hash` the file's id (64 hex characters), `size` bytes as stored, `mime` required; `key` and `salt` open it (22 base64url characters each) |
103
- | `image` | `{ blob, alt? }`: `alt` ≤ 2000, what it shows |
104
- | `position` | string 1–200 that sorts where a record goes (Positions, below) |
93
+ | Fragment | Shape |
94
+ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
+ | `when` | string 10–64, `x-kind: "when"`: RFC 3339 date-time (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
96
+ | `day` | string of 10, `x-kind: "day"`: `YYYY-MM-DD` |
97
+ | `url` | string 1–2048, `x-kind: "url"`: a web address |
98
+ | `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
99
+ | DID | string 1–256, `x-kind: "did"`: an account DID (built by `person`) |
100
+ | `money` | `{ amount, currency }`, `x-kind: "money"`, both required: `amount` a decimal string 1–32 (`"12.50"`), never a number; `currency` ISO 4217, 3 characters |
101
+ | `address` | `{ street, locality, region, postcode, country }`, each optional; `country` ISO 3166-1 alpha-2 |
102
+ | `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional; `lat` −90–90, `lon` −180–180, WGS 84; `cells` string 1–12[] (≤ 8), the geohash cells of `lat` and `lon` (see Places and areas) |
103
+ | `blob` | `{ hash, size, mime, name?, key?, salt? }`, `x-kind: "file"`: what `records.addFile` gives: `hash` the file's id (64 hex characters), `size` bytes as stored, `mime` required; `key` and `salt` open it (22 base64url characters each) |
104
+ | `image` | `{ blob, alt? }`, `x-kind: "image"`: `alt` ≤ 2000, what it shows |
105
+ | `position` | string 1–200, `x-kind: "position"`, that sorts where a record goes (Positions, below) |
105
106
 
106
107
  Until the dialect has `format` ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)), `when` and `day` are checked only for
107
108
  length. A `blob` is what `records.addFile` gives
@@ -125,17 +126,17 @@ anything, and only moderators and admins write in the collections in
125
126
 
126
127
  **Annotations**
127
128
 
128
- | Name | Body | Links | Rules |
129
- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------- |
130
- | `std.reaction` | **`emoji`** string 1–16; `respondingTo` DID; topic `respondingTo` | `about` → `*`, one | `onePer: [@author, link:about, emoji]` |
131
- | `std.comment` | **`text`** string 1–10000; `mentions` DID[] (≤ 64); `replyingTo` DID; `respondingTo` DID; topics `mentions`, `replyingTo`, `respondingTo` | `about` → `*`, one; `replyTo` → `std.comment`, one | — |
132
- | `std.tag` | **`label`** string 1–100 | `about` → `*`, one | `onePer: [@author, link:about, label]` |
133
- | `std.rating` | **`score`** integer 1–5; `review` string ≤ 10000 | `about` → `*`, one | `onePer: [@author, link:about]` |
134
- | `std.highlight` | **`quote`** string 1–10000; `prefix` string ≤ 500; `suffix` string ≤ 500; `note` string ≤ 10000 | `about` → `*`, one | — |
135
- | `std.pin` | `note` string ≤ 500 | `about` → `*`, one | `onePer: [link:about]` |
136
- | `std.report` | **`reason`** `spam`/`abuse`/`sexual`/`misleading`/`illegal`/`other`; `note` string ≤ 2000 | `about` → `*`, one | `onePer: [@author, link:about]` |
137
- | `std.label` | **`value`** string 1–64 | `about` → `*`, one | `onePer: [link:about, value]` |
138
- | `std.claim` | `note` string ≤ 500; `respondingTo` DID; topic `respondingTo` | `about` → `*`, one | `onePer: [link:about]` |
129
+ | Name | Body | Links | Rules |
130
+ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------- |
131
+ | `std.reaction` | **`emoji`** string 1–16; `respondingTo` DID; topic `respondingTo` | `about` → `*`, one | `onePer: [@author, link:about, emoji]` |
132
+ | `std.comment` | **`text`** string 1–10000; `mentions` DID[] (≤ 64); `replyingTo` DID; `respondingTo` DID; topics `mentions`, `replyingTo`, `respondingTo` | `about` → `*`, one; `replyTo` → `std.comment`, one; `shares` → `*`, one | — |
133
+ | `std.tag` | **`label`** string 1–100 | `about` → `*`, one | `onePer: [@author, link:about, label]` |
134
+ | `std.rating` | **`score`** integer 1–5; `review` string ≤ 10000 | `about` → `*`, one | `onePer: [@author, link:about]` |
135
+ | `std.highlight` | **`quote`** string 1–10000; `prefix` string ≤ 500; `suffix` string ≤ 500; `note` string ≤ 10000 | `about` → `*`, one | — |
136
+ | `std.pin` | `note` string ≤ 500 | `about` → `*`, one | `onePer: [link:about]` |
137
+ | `std.report` | **`reason`** `spam`/`abuse`/`sexual`/`misleading`/`illegal`/`other`; `note` string ≤ 2000 | `about` → `*`, one | `onePer: [@author, link:about]` |
138
+ | `std.label` | **`value`** string 1–64 | `about` → `*`, one | `onePer: [link:about, value]` |
139
+ | `std.claim` | `note` string ≤ 500; `respondingTo` DID; topic `respondingTo` | `about` → `*`, one | `onePer: [link:about]` |
139
140
 
140
141
  **People**
141
142
 
@@ -519,7 +520,7 @@ _Source: `packages/core/src/schemas/geo.ts` (`geohash`, `cellsOf`, `cellsAround`
519
520
 
520
521
  ## `std.call`
521
522
 
522
- Calls themselves are kept nowhere ([calls](calls.md)). Their history is a
523
+ Calls themselves are kept nowhere ([calls](../../calls/README.md)). Their history is a
523
524
  `std.call` record in the space, written only if the space defines `std.call`:
524
525
 
525
526
  | Field | Type | Meaning |
@@ -545,4 +546,4 @@ _Implementation detail:_ the call a device is in is kept in `sessionStorage`
545
546
  under `minca-call` as `{ space, call }`, so after a reload the page can offer to
546
547
  rejoin while the call is still going on.
547
548
 
548
- _Source: `packages/core/src/calls/calls.ts`, `packages/core/src/schemas/library/publishing.ts` (`call`). Tests: `packages/core/tests/calls.test.ts`._
549
+ _Source: `packages/calls/src/calls.ts`, `packages/core/src/schemas/library/publishing.ts` (`call`). Tests: `packages/calls/tests/calls.test.ts`._
package/docs/storage.md CHANGED
@@ -172,8 +172,12 @@ change and on close.
172
172
  directory store (`localPath` in `packages/cli/src/home.ts`). A command and
173
173
  the daemon share it, and the daemon finds the command's writes as it finds
174
174
  any directory store's (`reconcileFolder`). Writer keys are beside it in
175
- `writers/`; a slot left in the home from before is not read. `minca agent`
176
- still keeps its key and stores together in `<home>/agent`.
175
+ `writer-keys/`; a slot left in the home from before is not read, nor
176
+ `writers/`, where a minca from before the numbered lock keeps its keys, so
177
+ the two never sign with one key. `minca agent`
178
+ and `minca mcp` keep each session's key and stores together in a slot of
179
+ `<home>/agent`, beside the data folder the sessions share
180
+ ([actions](actions.md#the-agent-on-a-computer)).
177
181
  - **Elsewhere** it must be given: `folderStores` refuses to start without
178
182
  one, since a lasting key's places kept in memory would be handed out again
179
183
  after a restart.
@@ -326,16 +330,35 @@ How this library does the rest:
326
330
  (`fileRefsIn`, at most 16), so the envelope and the body always agree.
327
331
  - **Reading.** `records.readFile(space, ref)` gives the bytes: held here, or
328
332
  fetched from connected peers, one after another, then from mirrors,
329
- checking every chunk. It asks only for files a version this node keeps
330
- whole names. For a picture, `URL.createObjectURL(new Blob([bytes], { type:
331
- ref.mime }))` shows it.
333
+ checking every chunk. When none has them it waits, asking everyone again
334
+ whenever records change or a peer connects, and every 15 s, and resolves
335
+ once one does. It rejects for a file no version this node keeps whole
336
+ names, one whose id is here whole yet won't open as named, and when the
337
+ space closes. For a picture, `URL.createObjectURL(new Blob([bytes], {
338
+ type: ref.mime }))` shows it.
332
339
  - **Where chunks live.** Entries in the space's own store: `f/<id>/list`,
333
- `f/<id>/<n>`, and `f/<id>/own` with the time a file was added and not yet
334
- named. A data folder keeps these in this device's own stores, not the
340
+ `f/<id>/<n>`, `f/<id>/own` with the time a file was added here (0 once a
341
+ version names it), and `f/<id>/used` with when it was last fetched or
342
+ read. A data folder keeps these in this device's own stores, not the
335
343
  folder.
336
- - **What a node fetches.** A node with `fetchFiles: 'all'` (carriers and
337
- hosts) fetches every named file about 2 s after its records change. Any
338
- other node fetches a file when it is read.
344
+ - **What a node fetches.** Files follow records. A node fetches every file
345
+ named by a version it keeps whole about 2 s after its records change,
346
+ while the writer is likely still connected. A file this sweep found
347
+ nobody had is not asked of everyone again for 10 minutes, but is asked at
348
+ once of each peer that connects meanwhile.
349
+ - **A device's limits.** A node limits the files it did not add, in every
350
+ space: it fetches unread only files of up to 5 MiB, so photos and
351
+ documents come ahead and video when played. Past 256 MiB of them in a
352
+ space, counting each at the size its list proves, or every chunk held of
353
+ one never whole, it drops those fetched or opened longest ago, down to
354
+ 90%, at the start of each pass and as it fetches. One never whole goes
355
+ first. A file added here is never dropped, nor one being fetched or read;
356
+ one larger than the limit is dropped on the pass after it is read, and
357
+ fetched again at the next read. A dropped file that was whole keeps its
358
+ `used` entry, so it is not fetched unread again while a version names it;
359
+ reading it fetches it. The limit is per space, so a device in many spaces
360
+ holds more. A node with `fetchFiles: 'all'`, a carrier or host, fetches
361
+ and keeps every file.
339
362
  - **Serving.** A `want-file` is answered with at most 4 chunks; the asker
340
363
  asks again for the rest, so a large file never floods a connection.
341
364
  - **Keeping.** About 2 s after records change, files no version kept whole
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minca/core",
3
- "version": "0.1.13",
3
+ "version": "0.1.15",
4
4
  "type": "module",
5
5
  "description": "Self-sovereign P2P protocol for the browser — identity, schemas, storage, networking, and gossip sync",
6
6
  "repository": {
@@ -51,16 +51,6 @@
51
51
  "types": "./dist/elements/index.d.ts",
52
52
  "import": "./dist/elements/index.js"
53
53
  },
54
- "./react": {
55
- "@minca/source": "./src/react/index.ts",
56
- "types": "./dist/react/index.d.ts",
57
- "import": "./dist/react/index.js"
58
- },
59
- "./calls": {
60
- "@minca/source": "./src/calls/index.ts",
61
- "types": "./dist/calls/index.d.ts",
62
- "import": "./dist/calls/index.js"
63
- },
64
54
  "./inbox": {
65
55
  "@minca/source": "./src/inbox/index.ts",
66
56
  "types": "./dist/inbox/index.d.ts",
@@ -70,13 +60,12 @@
70
60
  "scripts": {
71
61
  "build": "rm -rf dist && tsc",
72
62
  "typecheck": "tsc --noEmit && tsc -p tests",
73
- "test": "node --experimental-vm-modules --import tsx --test --test-concurrency=4 --test-timeout=60000 --test-force-exit tests/*.test.ts",
63
+ "test": "node --experimental-vm-modules --import tsx --test --test-concurrency=8 --test-timeout=60000 --test-force-exit tests/*.test.ts",
74
64
  "prepack": "node ../../scripts/npm-readme.mjs",
75
65
  "postpack": "rm -f README.md",
76
66
  "prepublishOnly": "npm run build"
77
67
  },
78
68
  "devDependencies": {
79
- "@types/react": "^19.3.0",
80
69
  "@types/ws": "^8.18.2",
81
70
  "esbuild": "^0.28.2",
82
71
  "tsx": "^4.19.0",
@@ -95,14 +84,6 @@
95
84
  "@scure/base": "^2.4.0",
96
85
  "aws4fetch": "^1.0.20"
97
86
  },
98
- "peerDependencies": {
99
- "react": "^19.3.1"
100
- },
101
- "peerDependenciesMeta": {
102
- "react": {
103
- "optional": true
104
- }
105
- },
106
87
  "publishConfig": {
107
88
  "access": "public"
108
89
  }
@@ -1,140 +0,0 @@
1
- /**
2
- * Voice and video calls between the people in a space.
3
- *
4
- * Nothing here is new to the protocol. A call is live messages
5
- * (`node.spaces.send`) in the space it belongs to, and a WebRTC connection of
6
- * its own between each pair of people in it — the shape Matrix gives group
7
- * calls (MSC3401, Element Call's full mesh):
8
- *
9
- * ```
10
- * call.here { call, since, camera, muted } to the space, every few seconds while in it
11
- * call.ring { call } to one account: ring its devices
12
- * call.answered { call } / call.declined to the caller, and to your own other devices
13
- * call.cancel { call } the caller gave up ringing
14
- * call.signal { call, description | candidate } to one device: setting up the connection
15
- * call.leave { call } to the space: gone now, not in 15 seconds
16
- * ```
17
- *
18
- * The setup travels over the space's own peer connection, whose handshake
19
- * proved who is at the other end — so the offer, and the fingerprint of the
20
- * key the browser will insist on, really come from that person. A relay only
21
- * ever introduced the two devices; it never sees a call.
22
- *
23
- * Only members of the space (anyone holding a role) are rung by, heard in or
24
- * connected to a call; a view-only reader of a public space is not.
25
- *
26
- * A call belongs to the space, not to a screen: it keeps the space open
27
- * (`spaces.hold`) for as long as it runs, so moving between spaces
28
- * never interrupts it. One call at a time.
29
- *
30
- * Each connection is made with an audio and a video transceiver from the
31
- * start. Turning the camera on or off, or sharing the screen, swaps the track
32
- * a sender carries and never renegotiates — so neither side can offer at the
33
- * same moment as the other, and the side with the lower session DID always
34
- * makes the offer.
35
- */
36
- import type { P2PNode } from '../node/types.js';
37
- export interface CallsOptions {
38
- /** How a WebRTC connection is made. `new RTCPeerConnection` by default. */
39
- readonly createConnection?: (config: RTCConfiguration) => RTCPeerConnection;
40
- /** Camera and microphone. `navigator.mediaDevices.getUserMedia` by default. */
41
- readonly getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
42
- /** The screen, for sharing it. `navigator.mediaDevices.getDisplayMedia` by default. */
43
- readonly getDisplayMedia?: (constraints: DisplayMediaStreamOptions) => Promise<MediaStream>;
44
- /** How a set of tracks becomes something a `<video>` can show. `new MediaStream` by default. */
45
- readonly createStream?: (tracks: ReadonlyArray<MediaStreamTrack>) => MediaStream | null;
46
- /** Where the call you're in is remembered, to offer rejoining after a reload. `sessionStorage` by default; null for nowhere. */
47
- readonly storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null;
48
- /** How often you say you're in a call. Default 5 s. */
49
- readonly heartbeatMs?: number;
50
- /** How long without hearing that someone is gone. Default 15 s. */
51
- readonly goneMs?: number;
52
- /** How long a ring rings before it's a missed call. Default 45 s. */
53
- readonly ringMs?: number;
54
- }
55
- /** Someone else in the call you're in: one device of theirs */
56
- export interface CallPeer {
57
- /** Their device's session DID */
58
- readonly peer: string;
59
- /** Their account */
60
- readonly account: string;
61
- /** What they send: sound, and video when their camera is on. Null until it arrives. */
62
- readonly stream: MediaStream | null;
63
- readonly muted: boolean;
64
- readonly camera: boolean;
65
- readonly connection: 'connecting' | 'connected' | 'failed';
66
- }
67
- /** The call you're in */
68
- export interface CurrentCall {
69
- readonly id: string;
70
- readonly space: string;
71
- /** When you joined it, ms */
72
- readonly joinedAt: number;
73
- /** Your own camera and microphone, for showing yourself */
74
- readonly local: MediaStream | null;
75
- readonly muted: boolean;
76
- readonly camera: boolean;
77
- readonly sharing: boolean;
78
- readonly people: ReadonlyArray<CallPeer>;
79
- /** Who you're ringing, while it rings — and what came of it, for a moment after */
80
- readonly outgoing: {
81
- readonly to: string;
82
- readonly since: number;
83
- readonly state: 'ringing' | 'declined' | 'missed';
84
- } | null;
85
- /** Something went wrong that you should hear about: no microphone, say */
86
- readonly problem: string | null;
87
- }
88
- /** Someone ringing you */
89
- export interface IncomingCall {
90
- readonly id: string;
91
- readonly space: string;
92
- /** The caller's account */
93
- readonly from: string;
94
- readonly since: number;
95
- }
96
- /** A call going on in a space you have open, that you're not in */
97
- export interface CallAround {
98
- readonly id: string;
99
- readonly space: string;
100
- /** Accounts in it, each once */
101
- readonly people: ReadonlyArray<string>;
102
- /** When the first of them joined, ms */
103
- readonly since: number;
104
- }
105
- export interface CallsState {
106
- readonly current: CurrentCall | null;
107
- readonly ringing: ReadonlyArray<IncomingCall>;
108
- readonly around: ReadonlyArray<CallAround>;
109
- /** The call you were in before this page loaded, while it's still going on */
110
- readonly rejoin: CallAround | null;
111
- }
112
- export interface CallOptions {
113
- /** Start with the camera on. Default false: sound only. */
114
- readonly video?: boolean;
115
- }
116
- export interface Calls {
117
- /** What's going on now. The same object until something changes. */
118
- getState(): CallsState;
119
- subscribe(listener: () => void): () => void;
120
- /** Joins the call going on in a space, or starts one. Leaves any other call first. */
121
- start(space: string, options?: CallOptions & {
122
- readonly call?: string;
123
- }): Promise<void>;
124
- /** Starts a call in a space, and rings one person there — all their devices, until one answers */
125
- ring(space: string, account: string, options?: CallOptions): Promise<void>;
126
- answer(id: string, options?: CallOptions): Promise<void>;
127
- decline(id: string): Promise<void>;
128
- leave(): Promise<void>;
129
- setMuted(muted: boolean): void;
130
- setCamera(on: boolean): Promise<void>;
131
- /** Shows your screen in place of your camera, until you stop it (or the browser does) */
132
- shareScreen(): Promise<void>;
133
- stopSharing(): Promise<void>;
134
- /** Stops offering `rejoin` */
135
- forgetRejoin(): void;
136
- /** Leaves any call and stops listening */
137
- close(): Promise<void>;
138
- }
139
- export declare function createCalls(node: P2PNode, options?: CallsOptions): Calls;
140
- //# sourceMappingURL=calls.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"calls.d.ts","sourceRoot":"","sources":["../../src/calls/calls.ts"],"names":[],"mappings":"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"}