@symbo.ls/frank

Bidirectional transformation between Symbols project JSON and filesystem formats. Bundles a symbols/ directory into a JSON object (toJSON), or converts a JSON project back into a filesystem structure (toFS).

API

toJSON(projectDir, options?)

Bundles a Symbols filesystem project into a JSON-serializable object. Uses esbuild to bundle all project modules into a single CJS file, loads it, and returns the resolved data with functions stringified.

import { toJSON } from '@symbo.ls/frank'

const project = await toJSON('/path/to/symbols')

// project.components  -> all components
// project.pages       -> all pages
// project.designSystem -> design system config
// project.state       -> app state
// project.functions   -> all functions (stringified)

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | entry | string | auto-detected | Custom entry file (defaults to context.js) | | stringify | boolean | true | Stringify functions for JSON transport | | tmpDir | string | .symbols_local/frank-tmp/ | Custom temp directory for bundled output | | external | string[] | [] | Additional packages to externalize | | scanAndFix | boolean | false | Free-var scan + scope rewrite (the publish/serve emission pipeline) | | verifySerialization | boolean | true | Verify-or-fail publish gate on the emitted output (scanAndFix mode only) | | resolveAssetUrl | function \| 'dataurl' | — | URL for a project file referenced as new URL('<path>', import.meta.url) (see below). smbls push uploads the file; 'dataurl' inlines it. Absent: nothing is resolved | | importMetaUrls | 'load' \| 'all' | 'load' (or symbols.json frank.importMetaUrls) | Which new URL(…, import.meta.url) calls are resolved (see below) | | authoredSource | boolean | true | Serialize each function as its authored text (see below). false, or SMBLS_FRANK_BUNDLE_FUNCTION_TEXT=1, emits esbuild's text of it, as before |

If no context.js exists, frank auto-generates one by discovering available project modules (state, components, pages, etc.).

Lazy groups. A context that declares lazy: { admin: () => import('./admin/index.js') } (see the @symbo.ls/router README, "Lazy Routes") is published as the COMPLETE project: frank evaluates each loader (esbuild inlines the dynamic import, so this runs code the bundle already holds), merges the group's pages, components, functions, methods and snippets into the canonical sections, replaces each route placeholder ({ lazy: 'admin', … }) in place by the group's page of the same route (a placeholder the group has no page for is dropped, with a warning unless its route is a wildcard), and removes lazy. The output equals the same project declared eagerly. Refused with a coded error: a lazy that is not an object of loader functions or a group that exports another section (FRANK_LAZY_GROUP_INVALID), a placeholder naming an undeclared group (FRANK_LAZY_GROUP_UNDECLARED), a loader that throws (FRANK_LAZY_GROUP_LOAD_FAILED), and a group name or route the app or an earlier group already defines with another value (FRANK_LAZY_GROUP_COLLISION). Each group folder's barrels get the duplicate-export check too. toFS writes the merged project eagerly — the split lives in the source tree.

Function text is the author's

Every function frank serializes is the text its author wrote — comments, quotes, spacing and names as in the source file — not esbuild's re-print of it. esbuild renames a binding that another file of the bundle also declares (function getLightboxSrc2) and drops every comment between statements; a fetched tree held that text, so each smbls fetch → smbls push renamed again (getLightboxSrc23) and the comments were gone after the first push.

The bundle is built with a source map. A live function's toString() is an exact slice of the bundle, so the bundle's function nodes say where it starts (identical text at several places is told apart by V8's [[FunctionLocation]]); the map gives the authored file and position, and the function that starts there is its authored text (authoredSource.js). The live function then answers toString() with that text, so frank's stringify, the free-variable scan and the CLI's transport diff all read the same one. A fetched tree pushes back byte for byte.

The authored text is used only when it is the SAME function as the bundle's: equal syntax trees once comments, formatting and the names of the function's own bindings are set aside, every free name spelled the same (a free undefined equals esbuild's void 0; a braced single statement equals the bare one). Anything esbuild changed beyond that — an import read through the bundle (import_x.y, x_default, a renamed module binding), define, a folded constant, lowered syntax, a patched asset URL — keeps the bundle text. FRANK_DEBUG_AUTHORED_SOURCE=1 names each function that keeps it, and why.

The verify-or-fail publish gate

With scanAndFix: true (what smbls push, smbls frank to-json and the runner use), the emitted output is validated AFTER all rewriting (verifyEmission.js). Findings throw an error with code: 'FRANK_VERIFY_FAILED' and a message naming every defect — file, export, identifier, line — so a publish that would ship broken code fails loudly at build time instead of succeeding into a silently-broken runtime. The checks:

1. No unresolvable identifiers — every emitted function string must parse, and every free identifier (nested function/arrow bodies included, with full scope tracking) must resolve to a param/local, an injected alias (__scope, __mod, …) or a known runtime global. The runtime revives these strings with a bare eval — anything else is a guaranteed ReferenceError.
2. __scope.X reads resolve — X must exist in the emitted globalScope, in a statically-declared element scope on the path, or be assigned in-function (npm injection).
3. Signature parity — the emitted parameter list must equal the source parameter list. Exception: the documented () → (el) injection for positionally-invoked factories. For functions.* / methods.* (invoked fn.call(element, ...args)) ANY drift is an error.
4. No dropped exports — every named export declared in functions/, components/, snippets/, methods/ source files must be present in the emitted bundle (the directory is scanned, not the index — missing-index-re-export drops are caught too).

Escape hatch (emergencies only): toJSON(dir, { verifySerialization: false }), or set SMBLS_NO_VERIFY_SERIALIZATION=1 in the environment (works through smbls push unchanged). If the gate blocked you and the finding is wrong, that is a gate bug — file it; don't leave the hatch enabled.

globalScope under scanAndFix

The free-variable scan classifies every name a function reads but does not bind, and the emitted globalScope is built from those classifications (helpers lifted, constants copied, mutables moved into Smut). It always carries the project's own globalScope.js exports as well: an export no function reads by a bare name — a value only el.context.globalScope.X reaches at runtime — ships as a scan-clean run ships it, and a name the classification decided on keeps that decision. A member that is only WRITTEN (el.context.globalScope.X = v, delete el.context.globalScope.X) is no free variable; a read (….X, ….X += v, ….X.y = v) is.

Asset URLs: new URL('<path>', import.meta.url)

Parcel, Vite and webpack resolve new URL('<relative path>', import.meta.url) to the URL of the file they emit (self-hosted, content-hashed fonts and images). frank bundles the project to CommonJS, where esbuild empties import.meta, so such a call that runs while the bundle loads used to throw TypeError: Invalid URL at bundle.cjs:<line> and fail the push (importMetaAssets.js). Now:

• Resolved — a call whose first argument is a relative path literal naming an existing file (a #fragment is kept) becomes new URL("<url>"), where <url> is what resolveAssetUrl({ file, specifier, importer, line, column }) returns. smbls push uploads the file to the project (or reuses an asset with the same sha256) and publishes its platform URL; smbls frank to-json inlines a data: URL. Font urls in designSystem, component scope and props, any value computed while the project loads, publish as that URL.
• Scope 'load' (default) resolves only the calls that run while the bundle loads — outside every function (an immediately invoked one counts), outside try statements — in the project bundle. Those are exactly the calls that used to crash, so no project that pushed before publishes anything different. A call inside a function body, a try-guarded call and app.js are left exactly as before.
• Scope 'all' ("frank": { "importMetaUrls": "all" } in symbols.json) also resolves calls inside function bodies, helpers frank lifts into globalScope, lazily imported modules and app.js. With a resolver, a call it cannot resolve (a non-literal path, a missing file, a query string) fails the build.
• Explained — a load failure that is still the import.meta.url case throws code: 'FRANK_IMPORT_META_URL', naming the project file, line and reason (dynamic path, call inside a function, missing file, no resolver) instead of Invalid URL.

Parcel (smbls start / smbls build) never runs this: local dev keeps its native hashed assets. A fetched project (toFS) contains the published URL as a plain string, not the new URL(…) call. Asset import statements (import font from './x.woff2') keep esbuild's dataurl loader.

Declared runtime dependencies that are not installed

dependencies.js is the runtime importmap (mermaid and the runner build the page's importmap from it). A bare import of a package it declares that esbuild cannot resolve where frank runs is stubbed like the fixed external list instead of failing with Could not resolve "<pkg>": an await import('<pkg>') publishes as import('<pkg>'), and a static import used inside functions is loaded at runtime by frank's npm-module rewrite. A package that is installed keeps bundling inline exactly as before; a package nothing declares still fails to resolve (package.json dependencies never reach the platform's importmap, so they do not count). A value computed from such a stub while the project loads would publish as "" and fails the build with code: 'FRANK_UNINSTALLED_DEPENDENCY_VALUE' (declaredDependencies.js).

Host-registered packages (@symbo.ls/sdk)

The page supplies a host-registered package; no CDN can serve it and the framework never bundles it (isHostRegisteredPackage, a mirror of HOST_REGISTERED_PACKAGES in packages/smbls/src/hostPackages.js). frank emits two forms:

• A static import (import { SDK } from '@symbo.ls/sdk') becomes a synchronous read of globalThis.__SMBLS_PKGS__['@symbo.ls/sdk'] with a named error on a miss. No dependencies entry.
• A literal dynamic import (import('@symbo.ls/sdk'), single or double quotes, code only) becomes the lazy marker lazyHostImportExpr('@symbo.ls/sdk') from @symbo.ls/utils (rewriteHostPackageDynamicImports, at all three emission sites, after the declared-library pass): registry first, then the page's on-demand loader, else a rejection with code: 'SMBLS_HOST_PACKAGE_NO_LOADER'. A mention inside a comment or a string, a member call x.import(…), import attributes, a template specifier and a subpath stay as written. No dependencies entry.

The page runtimes leave the SDK out of the first document only when every read in the payload is a marker (classifyHostPackageReads). A read is the specifier as a whole quoted literal; a mention in prose (a comment, an install command, a URL) reads nothing. frank publishes authored function text, so any other quoted '@symbo.ls/sdk' inside a function body makes the page inline the SDK again (it still works). A project that switches to the dynamic form must push with a CLI whose frank has this pass: an older frank publishes the import() as written, and the browser cannot resolve it.

toFS(data, distDir, options?)

Converts a JSON project object into a Symbols filesystem structure with proper directory layout, index files, and a generated context.js.

import { toFS } from '@symbo.ls/frank'

await toFS(projectData, '/path/to/output/symbols')

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | overwrite | boolean | false | Overwrite existing files |

Generated structure:

symbols/
  index.js              # re-exports all modules
  context.js            # aggregated default export for bundling
  config.js             # design system config flags
  state.js              # app state
  dependencies.js       # project dependencies
  components/
    index.js            # export * from each component
    Button.js
    Card.js
  pages/
    index.js            # default export with route mapping
    main.js             # / route
    about.js            # /about route
  functions/
    index.js
    initApp.js
  methods/
    index.js
  snippets/
    index.js
  designSystem/
    index.js            # default export merging all sub-modules
    color.js
    theme.js
    typography.js
  files/
    index.js

stringifyFunctions(value)

Recursively clones a value, converting all functions to their string representations for JSON serialization. Handles circular references via WeakMap and skips internal metadata keys (__fn, __fnMeta, __handler, __meta).

import { stringifyFunctions } from '@symbo.ls/frank'

const serializable = stringifyFunctions({
  onClick: (el) => el.update({ active: true }),
  nested: { handler: function () { return 42 } }
})
// { onClick: '(el) => el.update({ active: true })', nested: { handler: 'function () { return 42 }' } }

How bundling works

toJSON uses esbuild to bundle the project entry into a single CJS module:

1. Detects entry file (context.js, or generates one from discovered modules)
2. Bundles with esbuild — resolves all local imports, externalizes runtime packages (smbls, domql, etc.)
3. Injects browser API stubs (location, history, document, etc.) so modules that reference browser globals don't crash in Node.js
4. Loads the bundled CJS module, strips empty default: {} artifacts from CJS bundling
5. Optionally stringifies functions, returns the plain object
6. Cleans up temp files

Project modules

Frank recognizes these standard project modules:

| Module | Path | Export style | |--------|------|-------------| | state | ./state.js | default | | dependencies | ./dependencies.js | default | | sharedLibraries | ./sharedLibraries.js | default | | components | ./components/index.js | namespace | | snippets | ./snippets/index.js | namespace | | pages | ./pages/index.js | default | | functions | ./functions/index.js | namespace | | methods | ./methods/index.js | namespace | | designSystem | ./designSystem/index.js | default | | files | ./files/index.js | default | | config | ./config.js | default |

Web Worker files (workers/)

symbols/workers/<name>.js is one module Web Worker. Its global is the worker's own scope (self.onmessage = …). It may import packages.

Start it with the form every bundler resolves natively (the path is relative to the calling file):

new Worker(new URL('../workers/avifEncode.js', import.meta.url), { type: 'module' })

• smbls build (Parcel) and Vite emit each worker as its own hashed bundle, loaded only when it starts.
• toJSON ships each worker bundled (esbuild, one ES module, every import inlined) in the workers section: { <name>: { type: 'module', file: 'workers/<name>.js', code } }. A new URL('<file>', import.meta.url) inside the worker graph (a .wasm next to its glue) resolves through resolveAssetUrl (smbls push uploads it; 'dataurl' inlines it).
• In the toJSON output, every published caller's new URL('<…>/workers/<name>.js', import.meta.url) becomes new URL('/__smbls/workers/<name>.js', globalThis.location.href) (@symbo.ls/utils workerScriptPath). @symbo.ls/mermaid serves the worker's code there, same-origin, so new Worker accepts it. smbls build never runs frank: Parcel keeps its own hashed worker bundle.
• workers is publish data, not a context section. toFS writes a worker back only where the tree has no file of that name.
• frank-audit treats workers/ as a frank slot (no FA006); in a worker file FA409 allows self.X / globalThis.X writes (window stays banned).