@agentshouse/skills 0.1.0-c96bb2a2009d2 → 0.1.0-c99fae1f41245

package/guide/apps/local-first.md

@@ -5,7 +5,7 @@ How an App reads and writes its Rooms on the device, offline too.
 - The runtime holds every bound Room on the device and streams in every change from any device, App or agent. `query` and `observe` answer from the device and never wait on the network; `search` asks House ([Search rules](apps/search)).
 - Draw from `observe` at once, with no request of your own; an observation hears each later change by itself, so never poll, refetch or subscribe. An answer is `{ pending }` while a Room it reads has not reached this device or been prepared on it: draw the page without those documents; keep the empty state for a complete answer. `rooms` answers once the runtime knows the Rooms the page reaches. Offer binding a Room when it is empty while the sync status's `providerUnreachable` is false and `observe('connection-refusal')` answers `null`; any other empty list says only that nothing can be listed yet.
 - Show no loading state: draw the last state the device holds. A wait shows only after an act the User pressed whose answer comes from outside the stream, such as `bridge.callExternal`, until it arrives.
-- Write optimistically: write a Room Draft, then `save`. The change shows in every query at once as a Pending Change and reaches House when it can. `save` refuses at once, with its `code`, a change that is `stale`, `changed-underneath` or against the schema: say so and keep the form.
+- Write optimistically: write a Room Draft, then `save`. The change shows in every query at once as a Pending Change and reaches House when it can. `save` refuses at once, with its `code`, a change that is `stale`, `changed-underneath` or against the schema: say so and keep the form. After `changed-underneath`, draw the joined Room Draft and its `marks` ([Room Drafts](apps/room-drafts)).
 - Show what the runtime reports: `observe('queue', room)` lists changes House has not confirmed yet, and `observe('sync-status')`'s `attentionRequired` lists each change House refused, returned as a Room Draft with why, to save again or discard.
 - Keep what the User types in the Room Draft (`roomDraft.write`) as they type; it survives a new release replacing the page, a reload and another tab. Draw a form again only when its page changes, never on a streamed change.
 - A document has one Room Draft, shared by every tab and App, and `save` takes all of it. A write replaces every part and names the revision it read, so write onto the parts it holds; one from an older revision answers `stale` with the current Room Draft: show that one. A field part names as its `base` the value the page showed, `{ value }`, or `null` when the document has no such field.

package/guide/apps/room-drafts.md

@@ -15,21 +15,27 @@ current Room Draft.
 
 Save takes one Room and the Room Drafts of it to save, each with its revision, validates
 locally, and on success appends one Change Batch to that Room's queue and removes those Room
-Drafts. Refused as `stale`, `changed-underneath` naming each part whose base no longer
-matches the visible state, or a local validation rule, it creates nothing and leaves every
-Room Draft. A directory move or removal is that part on each Document and binary Path entry
-beneath it, saved together; moves into another Room, saved alone, are one Change Batch in
-both Rooms' queues. `saveParts(room, [{ path, parts }])` saves parts, each Path once and
-each new part with its base, the same way but writes no Room Draft: one held at a saved Path
-stays, one at a moved Path moves with it to a destination that holds none. Never save by
-writing back a Room Draft read before.
+Drafts. Refused as `stale`, `changed-underneath` naming each part changed underneath, or a
+local validation rule, it creates nothing and removes no Room Draft. On `changed-underneath`
+it first joins each one over the current Document under a new revision: show that one. A
+field, a move, a removal and a replaced file keep yours; a section, the preamble, and a
+whole Markdown whose sections do not match hold the current text, then yours; a whole
+Markdown otherwise joins section by section. `marks`, keyed like `parts`,
+names each part holding both sides with the `change`, `{ author, time }` or `null`, that
+saved the current side, and a field's or file's `current`. Offer only Save and Discard; a
+write keeps the marks of the parts it still names. A directory move or removal is that part
+on each Document and binary Path entry beneath it, saved together; moves into another Room,
+saved alone, are one Change Batch in both Rooms' queues. `saveParts(room, [{ path, parts
+}])` saves parts, each Path once and each new part with its base, the same way but writes no
+Room Draft: one held at a saved Path stays, one at a moved Path moves with it to a
+destination that holds none. Never save by writing back a Room Draft read before.
 
 Outcomes follow the Provider's answer. An Accepted Change Batch stays in the queue, drawn
 over the confirmed layer, until that layer reaches the Room Version it was accepted at.
 Conflicted and Rejected, and a change that no longer applies, each
-leave the queue and return as Room Drafts on their Documents, marked with why: the
-Provider's structured refusal code and fields as returned, not known to have applied, or
-withdrawn locally. The rest of the queue keeps synchronizing, and Sync Status requires
+leave the queue and return as Room Drafts on their Documents, joined as above and marked
+with why: the Provider's structured refusal code and fields as returned, not known to have
+applied, or withdrawn locally. The rest of the queue keeps synchronizing, and Sync Status requires
 attention until each returned Room Draft is saved or discarded. `observe('queue', room)`
 shows each Pending Change Batch, which keeps no outcome once it leaves. Transport failure,
 Provider unavailability and a refusal marked retryable, until the reset it names, keep

package/guide/apps/runtime-files.md

@@ -29,9 +29,11 @@ or remove one as a Document, its bytes following.
 - `<room-media room path width height alt>` draws an image, video or audio file of the
   Room. It reserves the box `width` and `height` set, in the file's own pixels, or a 16:9
   one, before any byte; asks for the file only as it nears the view; draws a file the
-  browser keeps from its bytes, offline too, and reads and keeps an image; plays a video
-  or audio file from the Provider's address loading only its metadata; asks again when a
-  shown file's address lapses; asks again while the file cannot be shown yet, such as
+  browser keeps from its bytes, offline too, and reads and keeps an image; shows a video's
+  first frame with a play mark and plays it only in House's full-screen viewer, which a
+  press on it opens, and plays an audio file, loading only either's metadata from the
+  Provider's address; asks again when a shown file's address lapses; asks again while the
+  file cannot be shown yet, such as
   while the Room does not hold it or House did not answer, until House refuses it for
   good; and shows its children where the file cannot be read.
 - `binaryFile.read(room, path, revision?)` answers `{ kind: 'binary', stream, byteLength,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/skills",
-  "version": "0.1.0-c96bb2a2009d2",
+  "version": "0.1.0-c99fae1f41245",
   "description": "The upstream Skills agents.house serves its agents, verbatim, and the texts it writes for them: the Guide, its own Skills among the pages, and the Agent instructions",
   "license": "MIT",
   "type": "module",