The front door names what the repo now ships

`0a104fe` bundled an app and a provider into this repository and the README's
"Where everything is" table still listed neither. That table is the front door —
someone reading it got an incomplete map of two top-level directories that ship.

Also states the thing the change could otherwise be read as: the SDK is still a
shell and a contract, not a framework you import. A bundled app registers a row
and calls verbs like any other, with no privileged access. VERIFIED rather than
asserted — nothing under `app/` references `apps/` or `providers/`, and SDK_OWNED
is unchanged, so the bundled app's verbs are as substitutable as anyone's.

CONFORMANCE, checked rather than assumed: I expected the drive and focus rows
saying "no shipped surface in this repository does this" to have gone stale.
Measured — ARTIFACTS uses the three annotation messages and does NOT use drive or
focus, so both rows are still accurate and are left alone. Understating the
product costs as much as overstating it, and so does correcting a row that was
right.

What DID change is that annotations now has the in-repo consumer its siblings
still lack, and that row is added — attributed to the QA seat that requested the
seams and verified the migration, since evidence produced by the author of a
feature is a different claim from evidence produced by someone else. No counts are
restated here; they belong to that seat's proof and would rot in this file.

285 tests.
This commit is contained in:
mvschwarz committed 2026-08-05 06:29:56 -07:00
1 parent 0a104fe038
commit f6f3c66d5d
2 files changed
+9

No files matched your search

+8
View File
@@ -26,6 +26,14 @@ Open http://127.0.0.1:8890/ — the shell. It starts with one surface on the rai
| `app/surfaces.json` | The surface manifest the shell renders. |
| `app/surfaces/` | Surface pages live here, served at `/surfaces/…`. |
| `fixtures/` | The data behind the runtime's API verbs (rig floor state, files root). |
| `apps/` | Apps bundled with the SDK. An **app** is a surface plus whatever backend it needs — see `contract/app-manifest.md`. Most apps live in their own repositories; the ones here ship with the SDK because they exercise a primitive it defines. |
| `providers/` | The backends those bundled apps call. A provider declares how to run itself and which verbs it answers; nothing in `app/` depends on one. |
**The SDK is still a shell and a contract, not a framework you import.** A bundled
app is an app like any other — it registers a row and calls verbs, with no
privileged access to the runtime. It is here so that a primitive the contract
defines has a real consumer in the same repository, which is the thing the
conformance tables kept having to say "no" about.
## Starting a new surface
+1
View File
@@ -256,6 +256,7 @@ default path:
| marks surviving a runtime restart | **yes when `--annotations <file>` is configured**; in memory otherwise, and the layer says "session only" |
| human and agent marks rendered distinguishably | **yes** |
| an agent handle to add and remove marks | **yes** — `window.studioAnnotations.annotate()` / `.remove()` / `.list()` |
| **a SHIPPED app in this repository that actually consumes these seams** | **yes** — the bundled ARTIFACTS app uses the context, target and refresh messages and holds no annotation implementation of its own. Its migration was browser-verified by the QA seat that requested the seams, not by the author of them; the per-page isolation and element anchoring were measured against a live studio after a full restart. **This is the row the sibling primitives still answer "no" to** — `focus.md` and `drive.md` have no in-repo consumer, and both say so |
| **a mark anchored across a CROSS-ORIGIN surface** | **no.** A cross-origin iframe cannot be read for element identity, so marks there are spatial only and say so. Same-origin surfaces get element anchoring |
| **agreement about a mark between two people watching at once** | **no.** Last write for a scope wins. Concurrent annotation needs the write-path concurrency `change-signal.md` deliberately excludes, and inventing it before two real watchers exist would be the wrong shape |