-
Private-beta requirement
+
+
No account, connector, or hosted service is required.
- The production service currently accepts private-beta accounts. Use one
- of those accounts or the repository's local stack for this guide.
+ This example uses the real typed collection client and the deterministic
+ developer sandbox. It keeps every record in memory and makes no network
+ requests.
-
1. Add a bundled application manifest
-
- Save this file at public/.well-known/mdbase-app.json. The SDK
- loads the file from your own application and posts it inline during
- registration. The control plane receives the canonical JSON from the SDK.
-
-
+
Prerequisites
+
+ - Git;
+ - Node 24 LTS;
+ - Corepack, which installs the repository's pinned pnpm version.
+
+
+
1. Build the current packages
- The reverse-domain ID and name are display metadata. An approved grant binds
- the canonical manifest content to the application installation that
- completed authorization.
+ The Connect packages await their first npm publication. Build the exact
+ beta packages from the public repository for this example.
+
-
2. Install the SDK and validator
-
-
-
The packages are awaiting their first npm publication.
-
- The commands above are the public-beta installation path. Current
- development builds @mdbase/connect,
- {" "}@mdbase/connect-protocol, and
- {" "}@mdbase/connect-dev from the
- {" "}Connect repository.
-
-
-
Validate the bundled file during development and CI:
-
+
2. Download and run the complete example
- For a loopback development homepage and callback, add
- {" "}--allow-local. Production web homepages, icons, and
- browser callbacks use HTTPS. Native callbacks may use a private scheme
- derived from the application ID.
+ Save the example inside the developer package so Node resolves the local
+ workspace packages. The final command prints the result and exits.
-
-
3. Create one Connect client
-
+
- Keep this manager stable. It owns the set of saved connections and returns
- a separate collection-bound client for each one. Feature and repository
- code should receive that bound client, never ambient “current collection”
- state.
+ You can also
+ {" "}download the example file
+ {" "}and save it as
+ {" "}packages/devkit/sandbox-quickstart.mjs.
-
4. Start authorization from a user action
-
+
3. See what the example does
+
- Connect shows compatible collections and asks the user to approve the exact
- operations. The collection description becomes available after approval.
+ createSandbox() returns the same
+ {" "}MdbaseCollectionClient boundary used by a connected
+ collection. The example reads one seed record, creates a second record,
+ updates it with its revision token, and queries both task records.
-
5. Complete the callback
-
+
4. Check the expected result
+
- Call this once on the exact callback route listed in the manifest. PKCE is
- mandatory. On success, the client stores the grant-bound authorization and
- returns the newly approved collection-bound connection. The location
- helper restores the app-local return location, adds its collection ID, and
- removes temporary OAuth parameters.
+ A stale revision fails with a
+ {" "}concurrent_modification diagnostic. The sandbox also supports
+ typed CRUD, pagination, read defaults, and change cursors. CEL expressions,
+ authorization, routing, and filesystem behavior belong in real-stack
+ integration tests.
-
6. Query and update with a revision
-
+
5. Continue to a real collection
- Query results include a revision token. Pass it as
- {" "}if_revision when changing the record so a concurrent edit
- cannot be silently overwritten.
+ The next guide adds an application manifest, a provisionable workout
+ contract, browser authorization, and one approved local or hosted
+ collection.
-
-
Use a stable collection ID in app URLs.
-
- MdbaseBrowserLocation writes
- {" "}?collection=<id>, follows browser back and
- forward navigation through onChange(), and auto-selects only
- when exactly one connection is saved. An explicit unavailable ID stays
- authoritative, so show the chooser or reconnect that ID. Collection IDs
- can appear in browser history and logs. They are opaque locators, not
- credentials. Names are display text and can change.
-
-
-
-
Resolve domain fields from the contract descriptor.
-
- Generic apps can use declared mdbase types directly. Domain applications
- should read the contract descriptors returned by describe(){" "}
- or use an adapter maintained by the owning application.
-
-
-
-
-
Design the manifest
-
Build one downloaded file
+
diff --git a/src/styles/global.css b/src/styles/global.css
index 31fa928..ae84a3d 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -294,6 +294,52 @@ code {
color: var(--ink-soft);
}
+.plain-sequence,
+.glossary-list {
+ margin-top: 2rem;
+ border-top: 1px solid var(--line-strong);
+}
+
+.plain-sequence {
+ padding: 0;
+ list-style: none;
+ counter-reset: plain-sequence;
+}
+
+.plain-sequence li,
+.glossary-list > div {
+ display: grid;
+ max-width: none;
+ padding: 1rem 0;
+ grid-template-columns: minmax(11rem, 0.35fr) minmax(0, 1fr);
+ gap: 1rem;
+ border-bottom: 1px solid var(--line);
+}
+
+.plain-sequence li {
+ grid-template-columns: 2.25rem minmax(11rem, 0.35fr) minmax(0, 1fr);
+ counter-increment: plain-sequence;
+}
+
+.plain-sequence li::before {
+ color: var(--ink-muted);
+ font: 500 0.62rem/1.5 var(--mono);
+ content: counter(plain-sequence, decimal-leading-zero);
+}
+
+.plain-sequence strong,
+.glossary-list dt {
+ color: var(--ink);
+ font-size: 0.86rem;
+ font-weight: 700;
+}
+
+.plain-sequence span,
+.glossary-list dd {
+ color: var(--ink-soft);
+ font-size: 0.84rem;
+}
+
.trust-table,
.profile-table,
.api-table {
@@ -412,6 +458,46 @@ code {
font-size: 0.84rem;
}
+.callout--success {
+ background: color-mix(in oklch, var(--surface) 88%, var(--signal));
+ border-color: color-mix(in oklch, var(--line) 72%, var(--signal));
+}
+
+.start-options {
+ display: grid;
+ margin-top: 1.25rem;
+ border-top: 1px solid var(--line-strong);
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.start-options > div {
+ padding: 1rem 1.25rem 1.1rem 0;
+ border-bottom: 1px solid var(--line);
+}
+
+.start-options > div + div {
+ padding-right: 0;
+ padding-left: 1.25rem;
+ border-left: 1px solid var(--line);
+}
+
+.start-options strong {
+ font-size: 0.9rem;
+}
+
+.start-options p {
+ margin-top: 0.4rem;
+ color: var(--ink-soft);
+ font-size: 0.82rem;
+}
+
+.start-options a {
+ display: inline-block;
+ margin-top: 0.75rem;
+ font-size: 0.78rem;
+ font-weight: 700;
+}
+
.docs-shell {
display: grid;
width: min(100% - 2rem, 96rem);
@@ -446,6 +532,22 @@ code {
display: grid;
}
+.docs-nav__group {
+ display: grid;
+}
+
+.docs-nav__group + .docs-nav__group {
+ margin-top: 1rem;
+ padding-top: 0.85rem;
+ border-top: 1px solid var(--line);
+}
+
+.docs-nav__group > strong {
+ margin-bottom: 0.25rem;
+ color: var(--ink-muted);
+ font: 500 0.56rem/1.3 var(--mono);
+}
+
.docs-nav nav a {
padding: 0.36rem 0;
color: var(--ink-soft);
@@ -660,6 +762,16 @@ code {
.docs-article {
padding-top: 2rem;
}
+
+ .start-options {
+ grid-template-columns: 1fr;
+ }
+
+ .start-options > div,
+ .start-options > div + div {
+ padding: 1rem 0;
+ border-left: 0;
+ }
}
@media (max-width: 42rem) {
@@ -675,6 +787,19 @@ code {
display: block;
overflow-x: auto;
}
+
+ .plain-sequence li,
+ .glossary-list > div {
+ grid-template-columns: 2rem minmax(0, 1fr);
+ }
+
+ .plain-sequence span {
+ grid-column: 2;
+ }
+
+ .glossary-list dd {
+ grid-column: 1 / -1;
+ }
}
@media (prefers-reduced-motion: reduce) {
diff --git a/src/styles/home.css b/src/styles/home.css
index d98f65b..21c3971 100644
--- a/src/styles/home.css
+++ b/src/styles/home.css
@@ -89,6 +89,14 @@
transform: translateY(12px);
}
+.home-body .chapter__status,
+.section-label {
+ margin: 0 0 1rem;
+ color: var(--muted);
+ font: 500 0.625rem/1.4 var(--mono);
+ letter-spacing: 0.01em;
+}
+
.home-body .chapter.is-active .chapter__inner {
transform: translateY(0);
}
@@ -99,6 +107,292 @@
letter-spacing: -0.05em;
}
+.home-body .chapter__actions--intro {
+ margin-top: 1.5rem;
+}
+
+.home-reference {
+ position: relative;
+ z-index: 3;
+ padding: clamp(5rem, 10vw, 9rem) clamp(1.25rem, 6.8vw, 6.5rem);
+ color: var(--ink);
+ background: var(--paper);
+ border-top: 1px solid var(--line);
+}
+
+.home-reference + .home-reference {
+ border-top-color: var(--line);
+}
+
+.home-reference__opening {
+ display: grid;
+ width: min(100%, 78rem);
+ margin-inline: auto;
+ grid-template-columns: minmax(16rem, 0.86fr) minmax(18rem, 0.65fr);
+ column-gap: clamp(2rem, 8vw, 8rem);
+}
+
+.home-reference__opening .section-label {
+ grid-column: 1 / -1;
+}
+
+.home-body .home-reference h2 {
+ max-width: 13ch;
+ font-size: clamp(2.65rem, 6vw, 5.25rem);
+}
+
+.home-reference__opening > p:last-child {
+ max-width: 55ch;
+ padding-top: 0.4rem;
+ color: var(--ink-soft);
+ font-size: clamp(1rem, 1.35vw, 1.125rem);
+ line-height: 1.62;
+}
+
+.home-reference__opening > p strong {
+ color: var(--ink);
+}
+
+.ecosystem-flow,
+.availability-list,
+.route-list,
+.fit-guide__questions,
+.tool-example {
+ width: min(100%, 78rem);
+ margin: clamp(3.5rem, 7vw, 6rem) auto 0;
+}
+
+.ecosystem-flow {
+ padding: 0;
+ list-style: none;
+ border-top: 1px solid var(--line-strong);
+}
+
+.ecosystem-flow li {
+ display: grid;
+ max-width: none;
+ padding: 1.3rem 0;
+ align-items: baseline;
+ grid-template-columns: 3rem minmax(0, 1fr) minmax(10rem, 0.35fr);
+ gap: 1rem;
+ border-bottom: 1px solid var(--line);
+}
+
+.ecosystem-flow li > span,
+.route-list i {
+ color: var(--muted);
+ font: 500 0.625rem/1.4 var(--mono);
+}
+
+.ecosystem-flow li > div {
+ display: grid;
+ align-items: baseline;
+ grid-template-columns: minmax(10rem, 0.38fr) minmax(0, 1fr);
+ gap: 1rem;
+}
+
+.ecosystem-flow strong {
+ font-size: 0.9rem;
+}
+
+.ecosystem-flow p {
+ color: var(--ink-soft);
+ font-size: 0.875rem;
+}
+
+.ecosystem-flow a,
+.orientation__runtime a {
+ color: var(--ink);
+ font-size: 0.78rem;
+ font-weight: 700;
+ text-underline-offset: 0.25rem;
+}
+
+.orientation__runtime {
+ width: min(100%, 78rem);
+ max-width: none;
+ margin: 1.25rem auto 0;
+ color: var(--muted);
+ font-size: 0.78rem;
+}
+
+.working-example {
+ background: var(--paper-soft);
+}
+
+.tool-example {
+ display: grid;
+ border-top: 1px solid var(--line-strong);
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.tool-example > div {
+ padding: 1.2rem 1.25rem 1.25rem 0;
+ border-bottom: 1px solid var(--line);
+}
+
+.tool-example > div + div {
+ padding-right: 1.25rem;
+ padding-left: 1.25rem;
+ border-left: 1px solid var(--line);
+}
+
+.tool-example > div:last-child {
+ padding-right: 0;
+}
+
+.tool-example span {
+ display: block;
+ color: var(--muted);
+ font: 500 0.625rem/1.4 var(--mono);
+}
+
+.tool-example strong {
+ display: block;
+ margin-top: 0.5rem;
+ font-size: 1rem;
+}
+
+.tool-example p {
+ margin-top: 0.45rem;
+ color: var(--ink-soft);
+ font-size: 0.82rem;
+ line-height: 1.55;
+}
+
+.tool-example a {
+ display: inline-block;
+ margin-top: 0.9rem;
+ color: var(--ink);
+ font-size: 0.76rem;
+ font-weight: 700;
+}
+
+.working-example__note {
+ width: min(100%, 78rem);
+ max-width: none;
+ margin: 1.25rem auto 0;
+ color: var(--muted);
+ font-size: 0.78rem;
+}
+
+.availability {
+ background: var(--paper);
+}
+
+.availability-list {
+ border-top: 1px solid var(--line-strong);
+}
+
+.availability-list > div {
+ display: grid;
+ padding: 1.2rem 0;
+ grid-template-columns: minmax(10rem, 0.38fr) minmax(0, 1fr);
+ gap: 1rem;
+ border-bottom: 1px solid var(--line);
+}
+
+.availability-list dt {
+ color: var(--muted);
+ font: 500 0.68rem/1.5 var(--mono);
+}
+
+.availability-list dd {
+ display: grid;
+ grid-template-columns: minmax(8rem, 0.3fr) minmax(0, 1fr);
+ gap: 1rem;
+ color: var(--ink-soft);
+ font-size: 0.875rem;
+}
+
+.availability-list dd strong {
+ color: var(--ink);
+}
+
+.route-list {
+ border-top: 1px solid var(--line-strong);
+}
+
+.route-list a {
+ display: grid;
+ max-width: none;
+ padding: clamp(1.2rem, 2.5vw, 2rem) 0;
+ align-items: baseline;
+ grid-template-columns: minmax(10rem, 0.38fr) minmax(0, 1fr) 2rem;
+ gap: 1rem;
+ color: var(--ink);
+ border-bottom: 1px solid var(--line);
+ text-decoration: none;
+}
+
+.route-list a:hover span,
+.route-list a:hover strong {
+ color: var(--accent);
+}
+
+.route-list span {
+ color: var(--muted);
+ font: 500 0.68rem/1.5 var(--mono);
+}
+
+.route-list strong {
+ max-width: 46rem;
+ font-size: clamp(1rem, 2vw, 1.35rem);
+ line-height: 1.35;
+}
+
+.route-list i {
+ font-style: normal;
+ text-align: right;
+}
+
+.fit-guide {
+ background: var(--paper-soft);
+}
+
+.fit-guide__questions {
+ border-top: 1px solid var(--line-strong);
+}
+
+.fit-guide details {
+ border-bottom: 1px solid var(--line);
+}
+
+.fit-guide summary {
+ position: relative;
+ padding: 1.2rem 3rem 1.2rem 0;
+ color: var(--ink);
+ font-size: clamp(0.95rem, 1.5vw, 1.1rem);
+ font-weight: 700;
+ list-style: none;
+ cursor: pointer;
+}
+
+.fit-guide summary::-webkit-details-marker {
+ display: none;
+}
+
+.fit-guide summary::after {
+ position: absolute;
+ top: 1.1rem;
+ right: 0;
+ color: var(--muted);
+ content: "+";
+ font: 400 1.15rem/1 var(--mono);
+}
+
+.fit-guide details[open] summary::after {
+ content: "−";
+}
+
+.fit-guide details p {
+ max-width: 65ch;
+ padding: 0 0 1.35rem;
+ color: var(--ink-soft);
+ font-size: 0.9rem;
+ line-height: 1.65;
+}
+
@media (max-width: 820px) {
.home-body::before {
background: linear-gradient(
@@ -144,6 +438,51 @@
font-size: 0.8125rem;
line-height: 1.5;
}
+
+ .home-reference__opening {
+ grid-template-columns: 1fr;
+ gap: 1.5rem;
+ }
+
+ .home-reference__opening .section-label {
+ grid-column: auto;
+ margin-bottom: 0;
+ }
+
+ .ecosystem-flow li {
+ grid-template-columns: 2rem minmax(0, 1fr);
+ }
+
+ .ecosystem-flow li > div {
+ grid-template-columns: 1fr;
+ gap: 0.35rem;
+ }
+
+ .ecosystem-flow li > a {
+ grid-column: 2;
+ }
+
+ .availability-list > div,
+ .availability-list dd,
+ .route-list a {
+ grid-template-columns: 1fr;
+ gap: 0.35rem;
+ }
+
+ .route-list i {
+ display: none;
+ }
+
+ .tool-example {
+ grid-template-columns: 1fr;
+ }
+
+ .tool-example > div,
+ .tool-example > div + div,
+ .tool-example > div:last-child {
+ padding: 1.15rem 0;
+ border-left: 0;
+ }
}
@media (max-width: 480px) {