smbls 3.14.837 → 3.14.838

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # smbls
 
+## 3.14.838
+
+### Patch Changes
+
+- xma.info report round (FW-XMA-EXCEPTIONS-UPSTREAM-1), its /simplify pass and the follow-ups.
+
+  - element: optional features (view events, `always` handler chains, plain-row diff, hydration, yielding mount) are feature slots — `create.js` installs all of them, `src/lean.js` none (the smbls embed); one chunked mount driver and one meter per task; the chunked first render costs about a third of what it did (a resumed row goes after the previous row, one `__ref` shape, the budget is read once); `whenConnected`; `onWindowLoad` after load reaches an element built off-document; a null/false row item under `childExtends` builds nothing; building an n-row list no longer scans the parent's keys per row.
+  - smbls: the embed is back under its 72 KiB cap and the iife is 2.6 % smaller (terser renames locals after esbuild in the two classic-script builds; maps chained); kits stay lazy in `smbls/core`, fetch is one chunk; live sync loads only when `wantsLiveSync`; a URL-loaded dependency registers in parcel builds.
+  - router: the newest navigation wins over one waiting on an async guard; no lazy chunk rides along a resumed route.
+  - default-config: accessible Dropdown writes its attributes straight to the nodes, one tab stop per list, an `active` write re-runs only the rows that change, a key-opened menu focuses its item during the reveal; Dialog and Icon clean-ups.
+  - styling (scratch, css, css-in-props): one compound-value resolver; CSS colour functions (`oklch()`, `color()`, `color-mix()`, `light-dark()`, `lab()`, `lch()`, `hwb()`) pass through compound values; border props read the scheme only in literal mode.
+  - fetch / brender: every server render starts from an empty query cache (seeds carry every request a page makes); the local adapter stays lazy; shared route loop for `smbls build` and `smbls brender`, `smbls brender --strict`.
+  - cli: every command that writes to the platform prints its target and needs a typed "production" or `--yes` for production; `smbls deploy --save` saves the provider, `-y/--yes` is consent; `deploy --dry-run` no longer pushes.
+  - frank-audit: FA205 reports only factory calls that run at module load.
+
 ## 3.14.837
 
 ### Patch Changes

package/README.md

@@ -88,6 +88,53 @@ init(config, {
 })
 ```
 
+## The first render
+
+The boot runs as short main-thread tasks: the task the entry script runs in
+ends when `create()` is called, then the design system, the shell (the app
+root) and the first page each start a task of their own, and the shell and the
+page are built in chunks of 10 ms (`@symbo.ls/element` yielding mounts).
+
+The first view is painted once. The root is built outside the document and
+goes in with one insertion when the shell and the first page are complete, so
+the first paint shows the whole first view, as when the boot was one task, and
+nothing on screen moves.
+
+```js
+create(App, { firstRender: 8 })                                // chunks of 8 ms
+create(App, { firstRender: { budget: 10, progressive: true } }) // show as it builds
+create(App, { firstRender: false })                            // the whole boot in one task
+```
+
+`progressive: true` attaches the root at once and the page as it builds:
+earlier first content, but what follows the routed content (a footer after the
+router's container) can move as the page grows.
+
+When things happen:
+
+- The promise `create()` returns resolves after the first view is in the
+  document and the first page's `onRender` and `onRouteChanged` have run. A
+  route behind an awaited guard renders later, as before: the shell goes in,
+  then the page — built outside the document in the same chunks and inserted
+  whole.
+- `DOMContentLoaded` and `load` can fire before the app is in the document
+  (the boot continues after the entry script's task). Code after `create()` in
+  the entry script runs before the design system is prepared.
+- The app root's own `onCreate` … `onRenderRouter` run before the root is in
+  the document — every other element's hooks always ran before their element
+  was attached. The first page's hooks, `onRouteChanged`, the scroll and the
+  hash target run in the document. No `onMounted` runs before the first view
+  is in.
+- An element whose children were built in later chunks fires `onCreate` …
+  `onRender` after its last child; every hook keeps the order of a one-task
+  build (see the element package README).
+- A project's own `domqlOptions.mountYield` wins over the 10 ms budget. After
+  the first render, reconciles, `if:` and navigations build in one go again
+  unless the project set `domqlOptions.mountYield`.
+- A boot over a pre-rendered (brender) page builds its shell and page in one
+  task over the server markup (only the entry script's task ends first); a
+  server render keeps the whole boot in one task.
+
 ## 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.
@@ -163,6 +210,32 @@ const Button = {
 
 Also includes `@symbo.ls/cli`, `@symbo.ls/fetch`, `@symbo.ls/sync`, and `@symbo.ls/helmet`.
 
+## Entries and bundle size
+
+| 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/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' }] }`.
+
+What loads only when switched on (both entries share this; in `smbls/core` each is a separate file, in the single-file builds it is part of the file):
+
+| Module | Loaded when |
+|--------|-------------|
+| `@symbo.ls/windows`, `@symbo.ls/dropdown`, `@symbo.ls/tooltip` | on by default; `windows: false` / `dropdown: false` / `tooltip: false` keeps each out |
+| `@symbo.ls/analyze`, `@symbo.ls/shorthand`, `@symbo.ls/inspect` | `analyze`, `shorthand`, `inspect` set |
+| `@symbo.ls/fetch` (with its REST adapter, one file) | `fetch` configured |
+| `@symbo.ls/sync` (live sync) | a live-sync transport the page may use — a collab `socketUrl` (`editor` or `settings`; on a page the platform published, only inside an editor session: framed, or `?liveSync`) or `editor.runtime: 'runner'` — unless `sync: false`; or the toasts: `notifications: true` |
+| the remote-project fetch of `createSync` / `createAsync` | an `editor` configuration with a `key` |
+
+`create()` starts every load its configuration needs at once, in the task it is called in, and awaits each before the first render, so nothing renders twice.
+
+In `smbls/core` an app that keeps a kit on pays one module request at boot: the kits it keeps load in parallel, after the entry has evaluated and before the first render (measured: windows 4,050 B, dropdown 5,487 B, tooltip 2,626 B gzip). Turn off the kits you do not use. A `<link rel="modulepreload">` for the kits an app keeps on — emitted by a Parcel plugin of the Symbols CLI, which has to read the app's configuration at build time — is the follow-up that takes this request off the boot's critical path.
+
+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.
+
 ## SEO metadata
 
 Define metadata on your app or pages. Values can be static or functions:

package/core.js

@@ -0,0 +1,52 @@
+'use strict'
+
+// The framework's public API WITHOUT the platform registry — `smbls/core`.
+//
+// `index.js` (the `smbls` entry, the IIFE, the cjs build) is this module
+// PLUS the registration of every bundled namespace — and of `index.js`'s own
+// namespace — on `globalThis.__SMBLS_PKGS__`, which frank-serialized code
+// reads synchronously. Holding a namespace keeps every export it names alive,
+// so no bundler can drop an unused export from a bundle that registers it
+// (xma.info report item 5). An app that runs no serialized code — no
+// published or fetched project/library functions, no raw JSON handed to
+// create() — never reads that registry, and builds against this module
+// instead: the dist ships it as `smbls/core` (dist/smbls.core.esm.js), whose
+// 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
+// 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
+// entries into one app: they are two bundles, so two copies of the runtime.
+// Select one for every importer of the bare `smbls` specifier (a bundler
+// alias).
+
+// v3.14 entry point - re-exports all framework packages
+
+// Core v3.14 primitives (NEW)
+export * from '@symbo.ls/signal'
+export * from '@symbo.ls/css'
+
+// Core framework
+export * from '@symbo.ls/utils'
+export { update, dispose, remove, REGISTRY, LIFECYCLE_EVENTS, DELEGATED_EVENTS, MIXINS, addDelegatedEvent, removeDelegatedEvent, registerEvent, cacheNode, detectTag, createHTMLNode, isValidTag, isSvgTag, SVG_TAGS, applyExtends, addMethods } from '@symbo.ls/element'
+export * from '@symbo.ls/state'
+
+// Attribute & CSS processing
+export * from 'attrs-in-props'
+export * from 'css-in-props'
+
+// Design system & default components
+export * from '@symbo.ls/scratch'
+export * from '@symbo.ls/default-config'
+
+// WASM acceleration (lazy-loaded)
+// Wire CSS engine hook so WASM auto-accelerates CSS generation when loaded
+export { loadWasm, isWasmLoaded, setCssEngineHook } from '@symbo.ls/wasm'
+import { setCssEngineHook } from '@symbo.ls/wasm'
+import { setWasmEngine } from '@symbo.ls/css'
+setCssEngineHook(setWasmEngine)
+
+// Main create functions
+export * from './src/index.js'