@proveanything/smartlinks 2.0.14 → 2.0.15

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.14  |  Generated: 2026-09-22T11:19:25.044Z
+Version: 2.0.15  |  Generated: 2026-09-22T15:00:20.418Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/deploying-apps.md

@@ -236,14 +236,24 @@ today.)
 
 ---
 
-## Wiring it into your build
-
-Registration is the **last step of your build** — after bundles are built and hashed. Run a
+## Wiring it into your build (the KEYED path — CI / controlled env / beta·stable)
+
+> ⚠️ **This is the deploy-key path — not the default for a Lovable dev publish.** If you build in
+> Lovable (no deploy key in the build), your dev publishes register via the **key-free `refresh-dev`
+> ping** in **[Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps)** — put *that* in `postbuild`, not the
+> binary below. Reach for `smartlinks-register-release` only where you (a) hold a deploy key and
+> (b) set `SMARTLINKS_CHANNEL` — i.e. a controlled dev/CI environment, or a formal **beta/stable**
+> deploy. In a keyless Lovable postbuild this binary **skips silently** (no channel ⇒ no-op), so a
+> dev publish would register *nothing* — that's the trap. One rule: **dev publish → `refresh-dev`;
+> keyed/formal deploy → `register-release`.**
+
+Registration is the **last step of a keyed build** — after bundles are built and hashed. Run a
 small script that reads your built manifest and POSTs it, and **exits non-zero on failure**
 so a bad install fails the publish.
 
-The SDK ships the script, so you don't copy-paste it — run it as your postbuild step. It reads
-your built manifest, POSTs it, prints any warnings, and exits non-zero on failure.
+The SDK ships the script, so you don't copy-paste it — run it as your postbuild step **in a keyed
+environment**. It reads your built manifest, POSTs it, prints any warnings, and exits non-zero on
+failure.
 
 ```jsonc
 // package.json
@@ -266,13 +276,16 @@ It is driven entirely by env vars, so the same command works for dev (Lovable) a
 
 > The full source is at `scripts/register-release.mjs` in the SDK package if you'd rather vendor it.
 
-Registration is gated by **`SMARTLINKS_CHANNEL`**, so the three Lovable build types behave correctly:
+Registration is gated by **`SMARTLINKS_CHANNEL`**, so a keyed build behaves correctly by intent:
 
 | Build | `SMARTLINKS_CHANNEL` | Result |
 |---|---|---|
-| **Preview / live-edit** | unset | **skips quietly** — never registers, never fails |
-| **Dev (Publish)** | `dev` | registers to `dev` with the workspace Build-Secret key + your Lovable `SMARTLINKS_BUNDLE_BASE_URL` |
-| **Prod (CI)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+| **Preview / live-edit / plain Lovable dev publish** | unset | **skips quietly** — never registers, never fails. (A Lovable dev publish is meant to register via the key-free `refresh-dev` ping in [Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps), not this binary.) |
+| **Controlled dev env (you hold a dev key)** | `dev` | registers to `dev` with the dev key + your `SMARTLINKS_BUNDLE_BASE_URL` |
+| **Prod (CI / formal deploy)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+
+> The middle row is a *controlled* dev environment where you deliberately hold a dev key and set the
+> channel — **not** a stock Lovable publish, which carries neither and so should use `refresh-dev`.
 
 **Two secrets, two scopes:** the **deploy key** is channel-scoped and can be a *workspace-level*
 Lovable Build Secret shared by every app (a dev key only writes `dev`, so sharing it is safe). The

package/dist/docs/host-dependency-contract.md

@@ -178,3 +178,24 @@ if (host && host.version !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
 The host publishes its live contract on `window.__SMARTLINKS_SHARED__` (`{ version, specifiers }`),
 which `getHostSharedDependencies()` reads. Import-map shim paths follow `importMapPathFor(specifier)`
 (`/sl-shared/<version>/<slug>.js`), so both the portal and the SDK generate identical paths.
+
+## Version retention — hosts MUST keep every published version (load-bearing)
+
+The version in the shim path (`/sl-shared/vN/`) exists **so multiple contract versions coexist**. A
+deployed app pins the version it was built against (`meta.sharedDependencies`) and resolves its shims
+from that path forever. Therefore:
+
+> **A contract bump is ADDITIVE. Generating `/sl-shared/v7/` MUST NOT delete `/sl-shared/v5/` or
+> `/sl-shared/v6/`.** The shims are tiny re-export files — keep them.
+
+If the host's shim generator *replaces* the previous version instead of *appending*, the versioning
+buys nothing: every bump silently breaks every already-deployed app not yet rebuilt (bare-specifier
+resolution failure → blank container — the exact failure this whole contract prevents). "The host
+serves all versions while apps migrate" is not aspirational; it's a hard requirement of the host.
+
+**Retiring a version:** only remove `/sl-shared/vN/` once no installed app still declares that
+`meta.sharedDependencies` version. You can determine that from the app registry (each app's declared
+version × where it's installed); until it's provably unreferenced, keep it. Prefer a long deprecation
+window over reclaiming a few KB.
+
+(The same rule applies to any versioned CSS-baseline paths — additive, never delete a live version.)

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.14  |  Generated: 2026-09-22T11:19:25.044Z
+Version: 2.0.15  |  Generated: 2026-09-22T15:00:20.418Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/deploying-apps.md

@@ -236,14 +236,24 @@ today.)
 
 ---
 
-## Wiring it into your build
-
-Registration is the **last step of your build** — after bundles are built and hashed. Run a
+## Wiring it into your build (the KEYED path — CI / controlled env / beta·stable)
+
+> ⚠️ **This is the deploy-key path — not the default for a Lovable dev publish.** If you build in
+> Lovable (no deploy key in the build), your dev publishes register via the **key-free `refresh-dev`
+> ping** in **[Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps)** — put *that* in `postbuild`, not the
+> binary below. Reach for `smartlinks-register-release` only where you (a) hold a deploy key and
+> (b) set `SMARTLINKS_CHANNEL` — i.e. a controlled dev/CI environment, or a formal **beta/stable**
+> deploy. In a keyless Lovable postbuild this binary **skips silently** (no channel ⇒ no-op), so a
+> dev publish would register *nothing* — that's the trap. One rule: **dev publish → `refresh-dev`;
+> keyed/formal deploy → `register-release`.**
+
+Registration is the **last step of a keyed build** — after bundles are built and hashed. Run a
 small script that reads your built manifest and POSTs it, and **exits non-zero on failure**
 so a bad install fails the publish.
 
-The SDK ships the script, so you don't copy-paste it — run it as your postbuild step. It reads
-your built manifest, POSTs it, prints any warnings, and exits non-zero on failure.
+The SDK ships the script, so you don't copy-paste it — run it as your postbuild step **in a keyed
+environment**. It reads your built manifest, POSTs it, prints any warnings, and exits non-zero on
+failure.
 
 ```jsonc
 // package.json
@@ -266,13 +276,16 @@ It is driven entirely by env vars, so the same command works for dev (Lovable) a
 
 > The full source is at `scripts/register-release.mjs` in the SDK package if you'd rather vendor it.
 
-Registration is gated by **`SMARTLINKS_CHANNEL`**, so the three Lovable build types behave correctly:
+Registration is gated by **`SMARTLINKS_CHANNEL`**, so a keyed build behaves correctly by intent:
 
 | Build | `SMARTLINKS_CHANNEL` | Result |
 |---|---|---|
-| **Preview / live-edit** | unset | **skips quietly** — never registers, never fails |
-| **Dev (Publish)** | `dev` | registers to `dev` with the workspace Build-Secret key + your Lovable `SMARTLINKS_BUNDLE_BASE_URL` |
-| **Prod (CI)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+| **Preview / live-edit / plain Lovable dev publish** | unset | **skips quietly** — never registers, never fails. (A Lovable dev publish is meant to register via the key-free `refresh-dev` ping in [Section A](#a-from-lovable--hit-publish-no-key-anywhere-recommended-for-lovable-apps), not this binary.) |
+| **Controlled dev env (you hold a dev key)** | `dev` | registers to `dev` with the dev key + your `SMARTLINKS_BUNDLE_BASE_URL` |
+| **Prod (CI / formal deploy)** | `stable` | registers to `stable` with the prod/master key; a missing key **hard-fails** |
+
+> The middle row is a *controlled* dev environment where you deliberately hold a dev key and set the
+> channel — **not** a stock Lovable publish, which carries neither and so should use `refresh-dev`.
 
 **Two secrets, two scopes:** the **deploy key** is channel-scoped and can be a *workspace-level*
 Lovable Build Secret shared by every app (a dev key only writes `dev`, so sharing it is safe). The

package/docs/host-dependency-contract.md

@@ -178,3 +178,24 @@ if (host && host.version !== SHARED_DEPENDENCY_CONTRACT_VERSION) {
 The host publishes its live contract on `window.__SMARTLINKS_SHARED__` (`{ version, specifiers }`),
 which `getHostSharedDependencies()` reads. Import-map shim paths follow `importMapPathFor(specifier)`
 (`/sl-shared/<version>/<slug>.js`), so both the portal and the SDK generate identical paths.
+
+## Version retention — hosts MUST keep every published version (load-bearing)
+
+The version in the shim path (`/sl-shared/vN/`) exists **so multiple contract versions coexist**. A
+deployed app pins the version it was built against (`meta.sharedDependencies`) and resolves its shims
+from that path forever. Therefore:
+
+> **A contract bump is ADDITIVE. Generating `/sl-shared/v7/` MUST NOT delete `/sl-shared/v5/` or
+> `/sl-shared/v6/`.** The shims are tiny re-export files — keep them.
+
+If the host's shim generator *replaces* the previous version instead of *appending*, the versioning
+buys nothing: every bump silently breaks every already-deployed app not yet rebuilt (bare-specifier
+resolution failure → blank container — the exact failure this whole contract prevents). "The host
+serves all versions while apps migrate" is not aspirational; it's a hard requirement of the host.
+
+**Retiring a version:** only remove `/sl-shared/vN/` once no installed app still declares that
+`meta.sharedDependencies` version. You can determine that from the app registry (each app's declared
+version × where it's installed); until it's provably unreferenced, keep it. Prefer a long deprecation
+window over reclaiming a few KB.
+
+(The same rule applies to any versioned CSS-baseline paths — additive, never delete a live version.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.0.14",
+  "version": "2.0.15",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",