@lockerverse/sdk 0.2.161 → 0.2.163

package/MIGRATIONS.md

@@ -0,0 +1,149 @@
+# SDK migrations
+
+This file ships in both @lockerverse/sdk and @lockerverse/react. Use the copy in
+the target installed release. This is an agent-run procedure, not an install
+script. Installing a package does not edit host code or guarantee these steps ran.
+
+## Upgrade procedure
+
+1. Before installation, record the resolved installed version of each package
+   from the lockfile or package manager, the host framework, and the features in
+   use. Do not use a dependency range as proof of the installed version.
+2. Select a published matching stable SDK/React pair. A copy-prompt version is a
+   minimum, not a request to downgrade. Preserve a newer matching stable pair.
+   Core-only consumers do not need to add React. Use the existing package manager
+   and update the real lockfile. Follow peer requirements in the target manifests.
+3. After installation, read this target file and SDK_RULES.md. React consumers
+   must also read guides/integration.md and each applicable resource guide.
+   Follow SDK_RULES.md to create or merge the short host-root AGENTS.md section
+   so future upgrades use this procedure even without a new integration prompt.
+4. For each affected package, apply all entries where old version < entry version
+   <= target version, from oldest to newest. Include releases skipped by the
+   upgrade. Use semantic version comparison, not string comparison. An Unreleased
+   section is not a published migration and must not be applied to a stable host.
+5. Apply required steps. Apply recommended steps when the feature and host support
+   them and they fit the task. Keep deliberate host choices. For every skipped
+   step, state why it does not apply or what prevents it. Do not silently count it
+   as complete. Do not replace a framework, change payment mode, or publish a site
+   merely because a migration recommends a capability.
+6. Run the host's relevant existing build and checks. Inspect initial HTML when
+   SSR applies and the browser behavior for the changed feature. Do not create
+   live transactions. Report old/new versions, applied entries, automatic changes,
+   skipped actions and reasons, check results, and any remaining work.
+
+If the old version is unknown, identify it from the prior lockfile or Git history.
+If it cannot be found, report that limit and use the baseline review below. Do not
+claim that every historical migration was applied. Read this file even if the
+version already matches: a previous upgrade may have missed host adoption steps.
+
+## Existing integration baseline through 0.2.161
+
+This guide starts with the current integration baseline. It is not a complete
+record of older breaking changes. For an integration created before this guide,
+review this section once, including when its version already matches the target.
+The feature guide and public types in the target package define the exact API.
+
+### Required when applicable
+
+- **Hosts that use both React and Core:** keep installed versions matched and use public entry points.
+  Read the installed contract instead of an old copied integration prompt.
+- **Auction media proxy:** if using mediaBaseUrl, pass the full loaded auction
+  snapshot to components and initialAuction. Forward w and f query parameters
+  unchanged. Check that a resized response has the expected dimensions and type.
+- **Public route identity:** keep configured community and auction identity fixed.
+  Use real item and return links. Handle missing items without selecting another
+  item silently. Follow the host router's missing-page behavior.
+- **Checkout and recovery:** preserve supported recovery state and private data
+  handling. Never restart an uncertain transaction to recover from a load error.
+
+### Recommended host adoption
+
+- **Existing SSR hosts:** load public data on the server and seed
+  useLockerverseAuction with initialAuction or useLockerverseAuctions with
+  initialAuctions. Keep public content outside client-only payment boundaries.
+  Keep that content visible during silent refresh. Verify it in the raw response.
+- **Dedicated auction item pages:** set itemHeadingLevel={1}; avoid a competing
+  page title heading. Embedded item views can keep the default level 2.
+- **Gallery:** set galleryImageSizes when the host differs from the default
+  full-width mobile / 45vw desktop layout. Check the first image before hydration
+  and selected photos after interaction. Keep full-screen sizing separate.
+- **Import boundaries:** use feature entry points such as
+  @lockerverse/react/auction-item and @lockerverse/react/auction-data. Remove host
+  imports that eagerly load payment UI when the page does not yet need it.
+- **Host metadata and assets:** check offer descriptions against current prices.
+  Keep local fonts, responsive photos, and background videos within the host's
+  performance budget. These are host tasks, not automatic SDK transformations.
+
+### Automatic SDK behavior in the baseline
+
+Supported auction media paths use responsive sizes through the configured proxy.
+The gallery gives the first photo high priority and uses eager/lazy loading for
+selected/other photos. Transaction headings follow the item heading level.
+Auction checkout code is deferred until payment or recovery needs it. These
+benefits require the supported components and data paths; custom host UI must
+adopt the corresponding APIs itself. The SDK cannot remove the host's own eager
+imports or server-render a browser-only website.
+
+## Versioned changes
+
+### 0.2.161 — Deferred auction checkout code
+
+Affected: @lockerverse/react auction item and transaction UI.
+
+- **Automatic:** the supported auction UI loads checkout code when payment or
+  recovery needs it. No public prop change is required.
+- **Recommended:** use the narrow auction imports and remove unused eager payment
+  imports from the host. Do not remove payment peers required by the chosen flow.
+- **Check:** compare initial page requests with checkout requests. Public item
+  content must remain available before checkout loads; recovery must keep its
+  existing state. Do not expect the total size of every reachable chunk to shrink.
+
+### 0.2.160 — Transaction heading hierarchy
+
+Affected: @lockerverse/react auction item UI.
+
+- **Automatic:** transaction and status headings follow the item heading level.
+- **Recommended:** dedicated pages should use itemHeadingLevel={1}. Embedded
+  views should retain the level that fits their surrounding page.
+- **Check:** inspect the rendered heading order, including transaction states.
+  This change must not require a new host CSS workaround or a widget remount.
+
+### 0.2.159 — Gallery loading and item heading controls
+
+Affected: @lockerverse/react auction item UI.
+
+- **Automatic:** selected photos load eagerly and other photos load lazily. The
+  first photo has high fetch priority; lazy photos can use automatic image sizing.
+- **Recommended:** set galleryImageSizes for a custom host container and use
+  itemHeadingLevel={1} on a dedicated item page. Read guides/auctions.md for the
+  supported props. Embedded views can keep the defaults.
+- **Check:** inspect the first response, image request sizes, and heading order.
+  Check gallery selection and full-screen viewing without changing image quality.
+
+### 0.2.158 — Responsive images through a configured proxy
+
+Affected: @lockerverse/react auction images and @lockerverse/sdk auction data.
+
+- **Automatic:** supported auction images retain responsive resize URLs through
+  the configured mediaBaseUrl instead of losing resizing on that proxy path.
+- **Required when using a proxy:** pass the full loaded snapshot to the UI and
+  server seed. Configure the host rewrite to forward w and f unchanged to the
+  media service. Do not reconstruct the snapshot and discard mediaBaseUrl.
+- **Check:** confirm resized response dimensions and content type through the
+  actual proxy. Signed, external, and unsupported URLs must keep their original
+  behavior. Hosts without a custom proxy do not need a proxy configuration change.
+
+## Entry format for future releases
+
+Add new version entries above older entries. Before publication, replace any
+Unreleased heading with the actual release version. Keep prior entries intact.
+Each entry must state:
+
+- Version and affected packages/features.
+- Required changes, with the old and new API or behavior for breaking changes.
+- Recommended host changes and the conditions where they apply.
+- Automatic improvements and cases that need no host edit.
+- Completion checks and any limits or manual follow-up.
+
+For a new installation, use the current feature guides and baseline instead of
+reproducing old APIs from migration examples.

package/README.md

@@ -12,6 +12,11 @@ Online documentation can describe a newer release. Import public package entry
 points, not private `dist` files. For ready-made React UI, use the README shipped
 with `@lockerverse/react`.
 
+Read [SDK quality rules](SDK_RULES.md) before integration changes. For every
+upgrade, read [MIGRATIONS.md](MIGRATIONS.md) from the target package and apply
+all applicable steps, including skipped releases. A version bump alone does not
+complete an upgrade. Record the old installed versions before installation.
+
 ## Usage guide
 
 - [Checkout and payment recovery](#checkout)

package/SDK_RULES.md

@@ -0,0 +1,122 @@
+# SDK quality rules
+
+These rules apply to SDK maintenance and host integration. Read the installed
+package README, public types, resource guide, and MIGRATIONS.md with this file.
+Use the instructions from the target release. Do not copy APIs from newer docs.
+
+## Keep the host instructions available
+
+On the first integration or upgrade, create or merge a short `Lockerverse SDK
+maintenance` section in the host project's root `AGENTS.md`. Preserve unrelated
+instructions and update an existing equivalent section instead of duplicating it.
+Use the block below. Do not copy this entire guide or pin a release in that file.
+For a monorepo, keep this pointer in the root and name the affected app directories;
+resolve node_modules and lockfiles from the relevant package-manager workspace.
+
+```markdown
+## Lockerverse SDK maintenance
+
+For any install, update, or integration edit involving @lockerverse/sdk or
+@lockerverse/react:
+- Record the old resolved package versions before installation. Use the existing
+  package manager; keep React/Core matched when both are used, without downgrades.
+- Read SDK_RULES.md and MIGRATIONS.md in the target installed package under
+  node_modules/@lockerverse/react/ (or @lockerverse/sdk/ for Core-only hosts).
+  React users must also read guides/integration.md and the relevant resource guides.
+- Apply all applicable migrations, including skipped releases, and review the
+  existing-integration baseline even if the version already matches. New
+  integrations use the current guides and baseline.
+- If files are missing, select a published matching stable release that includes
+  them without downgrading, or report the blocked step. Do not invent instructions.
+- If a tool already updated dependencies, recover the old versions from the prior
+  lockfile or Git history. Report old/new versions, applied steps, skipped steps
+  with reasons, and checks. A version bump alone does not complete a migration.
+```
+
+For Lovable, this short pointer can also be kept in workspace knowledge, scoped
+to tasks that use Lockerverse. Do not install the SDK in unrelated projects.
+Workspace knowledge covers projects that have not yet received their root file;
+the root file keeps the rule with the project when it moves to another workspace
+or agent. Do not assume files inside node_modules are read automatically.
+See [Lovable's knowledge documentation](https://docs.lovable.dev/features/knowledge).
+If the host file cannot be edited, report that persistence is incomplete.
+A package installation does not run these instructions or modify the host file.
+
+## Public content and search
+
+- In an existing server-rendered host, load public auction data in its server
+  loader. Pass the complete snapshot through the supported initial-data API.
+  Keep text, images, status, and real links in the first HTML response. Do not
+  put the whole auction in a client-only boundary to protect payment code.
+- Keep browser storage, Stripe, and browser globals outside server rendering.
+  Retain the seed or last good snapshot during refresh. Refresh silently; do
+  not add an “Updating auction” banner or replace ready content with a loader.
+  Show initial loading only when no data exists. Keep useful failure feedback.
+- Use real href links for item and return navigation. Preserve direct entry,
+  reload, Back, Forward, and opening in a new tab. The host must handle unknown
+  item URLs; do not silently show the first item for an invalid identity.
+- On a dedicated item page, use itemHeadingLevel={1}. Keep transaction headings
+  below the item heading. Embedded items normally use the default level 2.
+  Use public props, not DOM patches or private CSS selectors.
+- The host owns titles, descriptions, canonicals, robots rules, sitemap, HTTP
+  status codes, and structured data. Keep price and availability claims aligned
+  with current public data. Do not hard-code a second copy of an offer.
+- A browser-only app does not gain server rendering from an SDK update. Explain
+  this limit. Do not replace its framework or add a server without task scope.
+
+## Images, fonts, and initial download
+
+- Use supported responsive image URLs and sizes. A proxy URL alone does not
+  prove resizing. Check the returned dimensions, content type, and transfer size.
+- With mediaBaseUrl, preserve the complete auction snapshot and forward w and f
+  query parameters to the configured media service. Use only the supported
+  public media path. Preserve signed, private, external, and unsupported image
+  URLs and the existing original-image fallback.
+- Match galleryImageSizes to the host layout. Reserve image space to prevent
+  layout shifts. Load the first visible image eagerly with high priority; load
+  off-screen images lazily. Keep selected and full-screen photos clear at their
+  rendered size and device pixel ratio. Do not lower quality only for a score.
+- Import the narrow public entry point for the feature. Keep payment code and
+  optional Stripe peers out of unrelated catalog, event, and signup imports.
+  Defer auction checkout code until payment or recovery needs it.
+- Keep required first-screen styles available. Scope widget styles and inherit
+  host fonts where supported. Do not add remote fonts or global font rules to
+  widgets. The host owns font compression, preload choices, background video,
+  and page-wide CSS. Avoid preloading every font or media file.
+- Inspect the actual initial bundle and network requests when changing import
+  boundaries. A smaller entry file alone does not prove a smaller first load.
+
+## State, failures, and logging
+
+- Keep resource identity stable. Do not remount a widget for background refresh,
+  metadata changes, or styling changes. Preserve contact and checkout state.
+- Never reset or retry an uncertain bid or payment as a new transaction. Preserve
+  the supported recovery flow. Do not add automatic page reloads to unresolved
+  payment recovery. A failed dynamic import needs useful failure feedback;
+  repeating the same import is not a reliable recovery method in every browser.
+- Use the existing failure-only telemetry contract. Do not add routine request,
+  polling, success, or render logs. Report only the safe fields allowed by that
+  contract; do not serialize request bodies or arbitrary error objects.
+- Keep contact data, payment tokens, secrets, and recovery credentials out of
+  URLs, public loader data, metadata, analytics, console output, and logs.
+  Public configuration and public resource identity are not credentials.
+- Use the selected environment and supported public APIs. Do not introduce an
+  unrelated payment backend or change saved resource settings during an upgrade.
+
+## Maintainer completion rules
+
+- For every release, review MIGRATIONS.md. Add an entry for a changed public
+  contract, default, or host adoption step. Include useful optional improvements,
+  not only breaking changes. State when a change needs no host edit.
+- Include affected packages/features, required and recommended actions, unchanged
+  cases, and a way to check completion. Do not call a version bump a migration.
+- Use a concrete release version for dated entries. If the release version is
+  not yet known, put steps in an Unreleased section, then assign the actual
+  version before publication. Do not publish pending steps as completed history.
+- These two root Markdown files are the maintained source. The package builds
+  copy them into both npm packages. Do not edit generated package copies.
+- Use focused existing checks and inspect packed files for documentation changes.
+  Do not create tests just because a file changed. Do not use real bids, payments,
+  or signups for an integration check. Report checks not run and remaining limits.
+- Do not promise a Lighthouse score, indexing, or search rank. Package rules help
+  prevent regressions; website content, hosting, and external services also matter.

package/dist/types.js

@@ -1,2 +1,2 @@
-const e=`0.2.161`;var t=class extends Error{code;operation;reportable;recoveryRecommended;sdkVersion;serverCode;status;constructor({code:t,message:n,operation:r,reportable:i,recoveryRecommended:a=!1,serverCode:o,status:s}){super(n),this.name=`LockerverseSdkError`,this.code=t,this.operation=r,this.reportable=i,this.recoveryRecommended=a,this.sdkVersion=e,this.serverCode=o,this.status=s}};export{t as n,e as t};
+const e=`0.2.163`;var t=class extends Error{code;operation;reportable;recoveryRecommended;sdkVersion;serverCode;status;constructor({code:t,message:n,operation:r,reportable:i,recoveryRecommended:a=!1,serverCode:o,status:s}){super(n),this.name=`LockerverseSdkError`,this.code=t,this.operation=r,this.reportable=i,this.recoveryRecommended=a,this.sdkVersion=e,this.serverCode=o,this.status=s}};export{t as n,e as t};
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lockerverse/sdk",
-  "version": "0.2.161",
+  "version": "0.2.163",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Lockerverse/lockerverse-sdk.git",
@@ -39,7 +39,9 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "SDK_RULES.md",
+    "MIGRATIONS.md"
   ],
   "dependencies": {
     "valibot": "1.4.2"
@@ -93,7 +95,7 @@
     }
   ],
   "scripts": {
-    "build": "tsdown",
+    "build": "node ../../scripts/copy-package-instructions.mjs sdk && tsdown",
     "contract:backend": "node test/contract/verify-backend-contract.mjs",
     "contract:check": "node test/contract/generate-public-api.mjs check",
     "contract:generate": "node test/contract/generate-public-api.mjs generate",