smbls 3.14.857 → 3.14.859

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # smbls
 
+## 3.14.859
+
+### Patch Changes
+
+- 3aa9e6a: `@symbo.ls/sdk` on demand. A page whose code reads the SDK only through `await import('@symbo.ls/sdk')` gets no SDK bytes in its first document; the SDK loads on the first call, one instance per page, the same build the page would have inlined.
+
+  frank: a literal `import('<host-registered package>')` in code (never a comment, a string or a member call `x.import(…)`) is emitted as the lazy marker `@symbo.ls/utils` `lazyHostImportExpr(spec)` — registry first, else the page loader `globalThis[Symbol.for('smbls.importHostPackage')]`, else a named rejection `SMBLS_HOST_PACKAGE_NO_LOADER`. Before, frank emitted the `import()` verbatim: a bare private specifier that rejects in the browser. The static tier (`import { X } from '@symbo.ls/sdk'`) is unchanged.
+
+  utils: `hostPackages.js` holds the shared contract — the marker forms (a stability contract: forms are added, never edited), `classifyHostPackageReads(text, spec, range)` (`none` / `lazy` / `static`; every exact marker is set aside, any other mention is static, so a page inlines in every case it did before), `hostPackageSourcesTag` (the `window.__SMBLS_HOST_SOURCES__` declaration a lazy page carries) and `runtimeProvidesHostPackageLoader` (a page goes lazy only under an smbls runtime that installs the loader).
+
+  smbls: the host tier moves to `src/hostPackages.js` (re-exported by `frameworkRegistry.js`). New `importHostPackage(spec)` (also `Smbls.importHostPackage`), installed by the full entry as `globalThis[Symbol.for('smbls.importHostPackage')]`: one classic script per package from the page's declaration, with SRI; concurrent calls share one load; registers the global first-wins; named, retryable rejections (`LOAD_FAILED`, `TIMEOUT`, `NO_GLOBAL`) remove the failed script so a retry loads again. `smbls/core` installs nothing.
+
+  runner (`smbls start` / `smbls build`): a lazy payload gets the declaration instead of the inlined SDK, and the runner serves the SDK file at `/__smbls/host/sdk.<sha256-16>.js` (immutable; any other file under `/__smbls/host/` is a 404); `smbls build` writes it beside `index.html`. Static and SDK-free payloads are byte-identical to before.
+
+- b0240a2: The host-package tier leaves a build whose source reads no host-registered package. `smbls build` with `build.treeShakeFeatures` now has the optional feature `hostPackages`: the full entry's on-demand loader (`importHostPackage`) and the shared contract of `@symbo.ls/utils` `hostPackages.js` (the lazy marker forms, the error codes, `classifyHostPackageReads`, `lazyHostImportExpr`, the declaration writer, the asset path). Every utils export is `context.utils`, so a `smbls/core` app that never reads `@symbo.ls/sdk` carried all of it.
+
+  The CLI keeps the feature when any file its scan reaches reads `@symbo.ls/sdk`: the scan runs `classifyHostPackageReads` (frank's rule) over each file, and a static import, an `import()`, a lazy marker or any other mention counts. It also keeps the feature when the source names an export of the tier, or `keep` lists `hostPackages`. A dropped build keeps the names: each function reports the feature once and returns nothing, the two predicates answer `false`, and the marker forms and error codes are `null`. The full entry still installs the loader, and each call rejects with `SMBLS_HOST_PACKAGE_NO_LOADER` and a message that names the option. Node, the page runtimes, frank and the IIFE never set the flag, so nothing changes there.
+
+- e8eaf28: Framework parts that only `context.lazy` groups use leave the main bundle. `smbls build` with `build.treeShakeFeatures` and `"smblsEntry": "core"` scans the main code and each group's own code apart (comments aside). When only group code uses `inertOutside`, the bridge hooks (`onBridgeMount`) or `TooltipLayer`, the build moves them into one small file (`smbls.core.lazyParts-*.js`). smbls loads this file together with the first group load and installs the parts before the group merges, whether that load comes before or after the first render. A part the main code uses, or one `keep` names, stays in the main bundle with no extra request. A group whose entry file the build cannot name keeps every part in the main bundle. XMA: main bundle −2,495 B Brotli; the admin load gets one more request (4.2 KB Brotli).
+- f8d78c4: A lazy route can be built ahead as its group's real page (XMA question 6).
+  symbols.json `brender.lazyGroups: 'load' | ['group', …]` makes the build's
+  first navigation load the group and render the route as the group's page
+  (the group's `when` is asked at build time; false builds the placeholder).
+  The page names the groups it was built with (`<meta name="brender-lazy">`)
+  and `smbls build` preloads each group's chunk (`<link rel="modulepreload">`
+  after the page's own preloads, found through the chunk's source map;
+  `build.modulePreload: "strict"` fails the build without one). In the browser
+  the boot reads the tag into the new `context.lazyFirstView` (router): the
+  first navigation loads those groups and renders their pages, so the takeover
+  adopts the built page instead of mounting the placeholder over it. Public
+  pages can move out of the main bundle and still arrive built.
+
+  The default build (no `brender.lazyGroups`) is fixed the same way: a route
+  whose group loaded during the render (a context that declares `lazy`, e.g.
+  through `brender.context`) already showed the group's page, but the page
+  named no group, so the browser mounted the placeholder over it (1 adoption
+  miss; on a slow run the built page was removed and rendered again). The
+  router now records a first navigation that showed the placeholder and then
+  the group's page; the page names that group and preloads its chunk. The
+  built content does not change.
+
+- b11e6c6: `polyglot.defaultLang` may be a function `(polyglot) => code`, called each time the default is asked (utils `polyglotDefaultLang`; every reader of the default goes through `polyglotFallbackLang`). The `fetch.early` pre-boot script carries its source and calls it before it decides. The language the pre-boot `startLang(ctx)` hook chose for a page load is recorded by the script (utils `polyglotEarlyStartLang`) and is the start language in every `addressLang` mode: under `'strict'` an unprefixed page started in the static default and asked for its labels a second time. A visitor's own stored choice still never wins under `'strict'`; an admin whose hook returns `null` keeps its own rule.
+- 6ecdb94: `afterFirstView` create option (config.js / context.js / `create(App, { afterFirstView })`): `(app, state, context)` runs once per app, a task after the first view is in — after `create()` rendered it or adopted the pre-rendered page, after the first navigation settled — the moment fetch.early's `afterFirstView` hook has. An app no longer polls `window.__BRENDER_HYDRATION__` to learn that a built page was taken over. A hook that throws or rejects is reported, never rethrown. brender switches it off for its server renders.
+- a529b80: Server render and page replace (W7): `el.context.ssr` is true while a component renders in a server render, so app code can tell it runs there. smbls replaces a pre-rendered page in short tasks and swaps it in at once; an adoption that throws falls back to the one-task replace. brender exports its page-weight trims (text between sprite symbols no longer stops the sprite trim) and `stylesheetRules`, which turns a stored stylesheet text back into its rules. `smbls build`: each pre-rendered route carries its own icons after its content (Fix B), and the cli reads brender's page trims as optional exports, so an older brender still builds.
+- d42696c: frank: `workers/<name>.js` is a discovered folder of module Web Workers. `toJSON` ships each worker bundled (esbuild, one ES module, imports inlined) in a `workers` section (`{ <name>: { type: 'module', file, code } }`); a `new URL('<file>', import.meta.url)` inside the worker graph (a `.wasm` beside its glue) resolves through `resolveAssetUrl` (push uploads, `'dataurl'` inlines). `toFS` writes a worker back only where the tree lacks it. The app starts a worker with the bundler-native `new Worker(new URL('../workers/<name>.js', import.meta.url), { type: 'module' })`. frank-audit: `workers/` is a frank slot (no FA006) and FA409 allows `self.X` / `globalThis.X` writes in a worker file (`window` stays banned); FA701 documents head-metadata defaults.
+
+  helmet: the runtime head never writes a label's stand-in (a polyglot key whose language is still loading, `@symbo.ls/utils` `evaluateText`) — the tag keeps its value until the label lands — and on a head the build wrote (`<meta name="brender">` / `brender-stamp`), on its served path, the app root's metadata does not replace a tag the document carries until the app's values change (a language switch) or the reader navigates. Measured on dev.xma.info (3.14.856): the served title flipped to the app.js default, then to raw `ui.meta.*` keys, before the page's labelled title.
+
+  Platform half: `@symbo.ls/utils` `SMBLS_PATH_PREFIX` / `workerScriptPath` / `workerNameFromPath` are the one path contract. frank points every published caller's `new URL('…/workers/<name>.js', import.meta.url)` at `new URL('/__smbls/workers/<name>.js', globalThis.location.href)`. mermaid `resolveSmblsRequest` serves `data.workers.<name>.code` there (`text/javascript`, `no-cache` + ETag, `nosniff`), and its boot script no longer inlines `data.workers`.
+
+## 3.14.858
+
+### Patch Changes
+
+- 1cd3348: `smbls build` with `build.treeShakeFeatures` and `"smblsEntry": "core"` leaves out the smbls/core kits the configuration never switches on (`windows`, `dropdown`, `tooltip` set `false`; `shorthand`, `analyze`, `inspect` unset; no `editor`; no `'local'` fetch adapter): no file for them in the output (XMA: 16 fewer files, −81 KB js, −662 KB maps). A kit stays when the configuration uses it, when `keep` names it, or when the configuration cannot be read. New optional feature `capsize`: dropped when nothing gives a font metrics (no `useCapsize`/`metrics` key, no `fontFamily` set to a font of its table). With `build.treeShakeLibraries` the boot no longer carries `@symbo.ls/channels`; with `liveSync` dropped it no longer carries the sync applier's page tests. `build.treeShakeIcons` drops a default icon that the project's own design system replaces under the same name.
+
 ## 3.14.857
 
 ### Patch Changes

package/README.md

@@ -175,9 +175,23 @@ When things happen:
   node whose element is not built yet is held and dispatched again, once, on
   the same node when the adoption is done (an element already adopted handles
   its own events at once); input during the adoption does not close the
-  window. `firstRender: false` adopts in one task, as before; a page that
-  replaces the server markup (no registry, `hydrate: false`) renders in one
-  task; a server render keeps the whole boot in one task.
+  window. `firstRender: false` adopts in one task, as before.
+- A boot that REPLACES the server markup (no registry, `hydrate: false`, a
+  platform pre-render) builds in the same short tasks: the app is built
+  outside the document while the server's page stays on screen with its
+  styles, and the server's markup and styles go in the task that inserts the
+  app — one page or the other on screen, never both, never neither.
+  `window.__BRENDER_HYDRATION__` is `{ replaced: true }` before the app's
+  first hook runs, in tasks as in one task: code that tells an adoption from
+  a fresh build (`el.context.prerendered` and no flag yet) reads a fresh
+  build in every hook. The first page's hooks and `onRouteChanged` run in the
+  task that inserts the app, so a hook there that reads layout (`focus()`,
+  `getBoundingClientRect()`) makes the new page's first style and layout part
+  of that task; read layout after the first frame or in `afterFirstView`.
+  `progressive: true` does not apply to a replace; `firstRender: false`
+  replaces in one task, and so does the fallback of an adoption that throws
+  (it has taken back the server nodes it had claimed). A server render keeps
+  the whole boot in one task.
 - A pre-rendered page shows the data of its build (`smbls build` pages: until
   the next build). `el.context.prerender` is the build it comes from,
   `{ stamp, time }` (`<meta name="brender-stamp">`). When the page is flagged
@@ -193,6 +207,28 @@ When things happen:
   nothing extra. See `@symbo.ls/fetch`, "A pre-built page shows
   the data of its build".
 
+### When the first view is in (`afterFirstView`)
+
+Work that must not compete with the first view — an analytics beacon, a page
+view, warming the next route — goes in the `afterFirstView` create option
+(config.js, context.js, or `create(App, { afterFirstView })`):
+
+```js
+// config.js
+export default {
+  afterFirstView: (app, state, context) => { app.call('pageView') }
+}
+```
+
+It runs once per app, a task after the first view is in: after `create()`
+rendered it — on a pre-rendered page, after the adoption — and after the
+first navigation settled (a route behind an awaited guard renders later). It
+is the moment fetch.early's own `afterFirstView` hook runs, so an app needs
+no poll on `window.__BRENDER_HYDRATION__` to learn that a built page was
+taken over. Called as the root's `onCreate` is, `(app, state, context)`; a
+hook that throws (or rejects) is reported, never rethrown. A server render
+(brender) never runs it.
+
 ## Plugins
 
 domql supports a plugin system via `context.plugins`. Plugins hook into the element lifecycle and can extend how event handlers, props, and metadata are processed.
@@ -273,7 +309,7 @@ Also includes `@symbo.ls/cli`, `@symbo.ls/fetch`, `@symbo.ls/sync`, and `@symbo.
 | Import | File | What it is |
 |--------|------|------------|
 | `smbls` | `dist/smbls.esm.js` (+ `smbls.cjs`) | The full runtime: the public API **plus the platform registry** — every bundled package registered on `globalThis.__SMBLS_PKGS__` so published or fetched project code (frank-serialized functions, `smbls fetch --scope libs` libraries, raw JSON handed to `create()`) resolves its imports. One file. |
-| `smbls/core` | `dist/smbls.core.esm.js` + chunks | The same public API **without the registry** (no `registerHostPackages` / `HOST_REGISTERED_PACKAGES`), no Simone client, no socket.io. Code-split: each kit and platform plugin is its own file, downloaded only when the app's configuration switches it on. |
+| `smbls/core` | `dist/smbls.core.esm.js` + chunks | The same public API **without the registry** (no `registerHostPackages` / `HOST_REGISTERED_PACKAGES` / `importHostPackage`, and no on-demand host-package loader), no Simone client, no socket.io. Code-split: each kit and platform plugin is its own file, downloaded only when the app's configuration switches it on. |
 | `smbls/iife` | `dist/smbls.iife.js` | The full runtime as one script (`window.Smbls`) — what the platform serves. |
 
 Use `smbls/core` for an app that runs **no** published or fetched project code — that code reads the registry and gets `{}` without it. Select it for **every** importer of `smbls` at once (a bundler alias), never by importing both entries: they are two bundles, so two copies of the runtime. With the Symbols CLI and parcel, set `"smblsEntry": "core"` in `symbols.json`. With vite: `resolve: { alias: [{ find: /^smbls$/, replacement: 'smbls/core' }] }`.
@@ -294,6 +330,54 @@ In `smbls/core` an app that keeps a kit on pays one module request at boot: the
 
 Every dist bundle has a source map next to it (`<file>.map`, sources included). The embed's map is not linked from the file, to keep the embed's byte budget.
 
+## Host packages: the platform SDK
+
+`@symbo.ls/sdk` is a **host-registered package**: `smbls` (public on npm) never bundles it and no public CDN serves it — the page that runs the code supplies it. Project code reads it in one of two ways.
+
+**Static** — `import { SDK } from '@symbo.ls/sdk'` at the top of a file. frank emits a synchronous read of `globalThis.__SMBLS_PKGS__['@symbo.ls/sdk']` with a named error on a miss, and the page runtime inlines the SDK and registers it before boot:
+
+```js
+Smbls.registerHostPackages({ '@symbo.ls/sdk': sdkNamespace }) // before Smbls.create(...)
+```
+
+**On demand** — a literal `import('@symbo.ls/sdk')` inside the function that needs it:
+
+```js
+export const openAccount = async function () {
+  const { SDK } = await import('@symbo.ls/sdk')
+  const sdk = new SDK({ apiUrl })
+  // …
+}
+```
+
+frank rewrites that call into a fixed marker expression (`@symbo.ls/utils` `lazyHostImportExpr`). The page runtimes recognise the marker (`classifyHostPackageReads`): when **every** mention of the SDK in the boot payload is a marker, the first document carries no SDK bytes, only a small declaration of a same-origin, content-hashed, immutable file:
+
+```js
+window.__SMBLS_HOST_SOURCES__ = {
+  '@symbo.ls/sdk': { src: '/__smbls/host/sdk.<sha256-16hex>.js', integrity: 'sha384-…', global: 'SymbolsSDK' }
+}
+```
+
+On the first call the marker reads the registry, then asks `importHostPackage` (the full entry installs it as `globalThis[Symbol.for('smbls.importHostPackage')]`; hand-written code can call `Smbls.importHostPackage('@symbo.ls/sdk')`). The loader inserts one `<script>` for the declared file, registers the namespace, and resolves it. The semantics are the inline's: one SDK instance per page (registry first, one shared load, additive registration), the same SDK build the page would have inlined.
+
+A failure rejects with an `Error` that has `code`, `specifier` and `retryable`. Catch it and offer a retry:
+
+| `code` | When | `retryable` |
+|---|---|---|
+| `SMBLS_HOST_PACKAGE_LOAD_FAILED` | the file did not load (the script is removed; a retry inserts a new one) | yes |
+| `SMBLS_HOST_PACKAGE_TIMEOUT` | the file did not load in 30 s | yes |
+| `SMBLS_HOST_PACKAGE_NO_GLOBAL` | the file loaded but defined no global | yes |
+| `SMBLS_HOST_PACKAGE_NO_SOURCE` | the page declares no file and registered nothing — every server render | no |
+| `SMBLS_HOST_PACKAGE_NO_DOM` | no document to load into | no |
+| `SMBLS_HOST_PACKAGE_UNKNOWN` | the specifier is not host-registered | no |
+| `SMBLS_HOST_PACKAGE_NO_LOADER` | no smbls runtime on the page provides the loader | no |
+
+Rules for a page that should stay lazy:
+
+- Write only the on-demand form; no static `import … from '@symbo.ls/sdk'` anywhere in the page's parts (app, libraries, kits).
+- Name the specifier nowhere else inside a function body — frank publishes body comments and strings as written, and any other mention makes the page inline the SDK (it still works: the marker then answers from the registry).
+- Push with a CLI whose frank has the marker. An older frank publishes the `import()` as written, and a browser cannot resolve that bare private specifier.
+
 ## SEO metadata
 
 Define metadata on your app or pages. Values can be static or functions:

package/core.js

@@ -14,7 +14,8 @@
 // kits and platform plugins are separate files loaded only when switched on.
 //
 // The export list below is index.js's, minus the registry's own surface
-// (`registerHostPackages`, `HOST_REGISTERED_PACKAGES`); it is a copy, not an
+// (`registerHostPackages`, `HOST_REGISTERED_PACKAGES`, `importHostPackage` —
+// and index.js's install of that on-demand loader); it is a copy, not an
 // import of index.js, which would bring the registry along.
 // __tests__/coreEntry.test.js keeps the two lists in step, and from source
 // both entries share every module instance. Never import both PREBUILT