arcane-os 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.32.0
+
+- Export `profileUpdateFromSearchParams(searchParams)` from
+  `arcane-os/entities/User.js` for purchase-link profile updates. It maps
+  `subscription` (otherwise `subscription_key`), exact `TWiN`, `name`, `email`,
+  and `phone` to the existing User profile fields and omits empty or missing
+  selected values. A present `subscription` takes precedence even when empty.
+- Preserve normal `URLSearchParams` decoding, first repeated values, Unicode,
+  spaces, literal plus signs and leading zeros without further conversion.
+  Ignore `zipcode` and unrelated keys. The helper neither mutates the URL nor
+  saves; apps retain hydration, draft protection and `updateExplicit` ownership.
+- Keep the standalone root/direct npm path behavior released in `0.31.0` and
+  all existing User setters, persistence and browser singleton lifecycle.
+
 ## 0.31.0
 
 - Standalone applications use their repository root and installed npm package

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.31.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.32.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -85,7 +85,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.31.0 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.32.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```

package/docs/reference/inventory/runtime-entities.json

@@ -5,7 +5,7 @@
     "bundleVersion": "0.8.12"
   },
   "moduleCount": 14,
-  "exportCount": 29,
+  "exportCount": 30,
   "modules": [
     {"file":"runtime/arcane/entities/ApiModelRecord.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/Calculation.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
@@ -19,7 +19,7 @@
     {"file":"runtime/arcane/entities/Preference.js","exports":["default","preferenceSchema"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/TerminalSession.js","exports":["default","terminalShells"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/Theme.js","exports":["arcaneDarkThemeTokens","arcaneLightThemeTokens","default","themeColorToHex","themeTokens"],"availability":"cross-host/dom-when-applied","normalization":"normalized/mixed"},
-    {"file":"runtime/arcane/entities/User.js","exports":["default"],"availability":"browser/native-webview","normalization":"mixed"},
+    {"file":"runtime/arcane/entities/User.js","exports":["default","profileUpdateFromSearchParams"],"availability":"browser/native-webview","normalization":"Existing User lifecycle is unchanged; profileUpdateFromSearchParams purely maps nonempty supplied URLSearchParams values without further decoding, trimming, or persistence."},
     {"file":"runtime/arcane/entities/Weather.js","exports":["WeatherDay","WeatherLocation","WeatherObservation","WeatherSnapshot"],"availability":"cross-host","normalization":"normalized"}
   ]
 }

package/docs/reference/runtime-entities.md

@@ -1,9 +1,11 @@
 # Arcane runtime entity modules
 
-The synchronized runtime ships 14 entity modules with 29 public ESM bindings.
+The synchronized runtime ships 14 entity modules with 30 public ESM bindings.
 This page explains each module's capability and host assumptions. The exact
 constructor/function/value contracts are canonical in the
-[Arcane shared entity inventory](core/arcane-entities.md).
+[Arcane shared entity inventory](core/arcane-entities.md), with later SDK
+additions documented below and in the current
+[runtime entity inventory](inventory/runtime-entities.json).
 
 Entity creation and serialization are usually cross-host. Methods that touch
 DOM, DBOPFS, local storage, AI, or object URLs require the corresponding browser
@@ -25,7 +27,7 @@ or native-WebView dependency.
 | `Preference.js` | `default`, `preferenceSchema` | Boolean, number, select, and text preference definitions. | Cross-host; normalized. |
 | `TerminalSession.js` | `default`, `terminalShells` | Frozen terminal session identity, shell, and state. | Cross-host; normalized. |
 | `Theme.js` | five exports | Semantic theme tokens, conversion, serialization, and DOM application. | Values cross-host; apply/clear need DOM; normalized/mixed. |
-| `User.js` | `default` | User preferences/profile state with DBLS/DBOPFS lifecycle. | Browser/native WebView; storage behavior mixed. |
+| `User.js` | `default`, `profileUpdateFromSearchParams` | User preferences/profile state and pure URL-query profile mapping. | Browser/native WebView module; mapping itself has no side effects. |
 | `Weather.js` | four classes | Frozen location, observation, day, and snapshot weather entities. | Cross-host; normalized. |
 
 ## ApiModelRecord.js
@@ -272,12 +274,41 @@ Owns persisted user preference/profile fields, explicit-preference updates,
 fresh reads, saves, and JSON projection. It installs `window.user` after its
 DBLS/DBOPFS lifecycle and emits `user-entity-loaded`.
 
+### profileUpdateFromSearchParams(searchParams)
+
+Named export from `arcane-os/entities/User.js`. Pass an existing
+`URLSearchParams`; the helper returns a new ordinary profile-update record.
+
+| Query parameter | Profile field |
+| --- | --- |
+| `subscription`, otherwise `subscription_key` | `subscription_key` |
+| `TWiN` (exact case) | `license_key` |
+| `name` | `username` |
+| `email` | `email` |
+| `phone` | `phone` |
+
+Presence selects `subscription` over the fallback, even when its first value
+is empty. Missing or empty selected values are omitted. Repeated parameters
+use their first value, following `URLSearchParams.get()`. Normal URL decoding
+occurs once when the caller creates the parameters; the helper preserves the
+decoded strings, including spaces, Unicode, literal plus signs, and leading
+zeros, without trimming, further decoding, or numeric conversion. Whitespace
+is a supplied nonempty value. Unknown keys, including `zipcode`, are ignored;
+no extra name fields are inferred.
+
+The helper does not mutate the parameters, read or change the current URL,
+hydrate, render, or save. Importing `User.js` still has its existing browser
+singleton lifecycle. Applications own URL capture/removal, manual-draft
+protection, readiness, and their awaited `user.updateExplicit(update)` call.
+
 ### Example
 
 ```javascript
-import UserEntity from '/arcane/entities/User.js';
+import {profileUpdateFromSearchParams} from 'arcane-os/entities/User.js';
 
-console.log(typeof UserEntity.prototype.toJSON);
+const params = new URLSearchParams('name=Captain+Moonboots&phone=00123');
+const update = profileUpdateFromSearchParams(params);
+// {username: 'Captain Moonboots', phone: '00123'}
 ```
 
 ## Weather.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/entities/User.js

@@ -25,6 +25,34 @@ import {
  */
 import DBOPFS from '../modules/DBOPFS.js';
 
+/**
+ * Maps supplied URL query values to an explicit profile update without saving.
+ * URLSearchParams owns decoding; preserve its first value exactly as returned.
+ * A present subscription, even empty, takes precedence over subscription_key.
+ *
+ * @param {URLSearchParams} searchParams
+ * @returns {Object<string,string>}
+ */
+export function profileUpdateFromSearchParams(searchParams){
+    const update={
+        subscription_key:searchParams.get(
+            searchParams.has('subscription')?'subscription':'subscription_key'
+        ),
+        license_key:searchParams.get('TWiN'),
+        username:searchParams.get('name'),
+        email:searchParams.get('email'),
+        phone:searchParams.get('phone')
+    };
+
+    for(const key of Object.keys(update)){
+        if(update[key]===null||update[key]===''){
+            delete update[key];
+        }
+    }
+
+    return update;
+}
+
 function createDefaultDashboard(){
     return { charts:{} };
 }