jq79 0.7.2 → 0.7.3

package/README.md

@@ -178,6 +178,7 @@ When the fetch resolves, the assignments to `firstName`/`lastName` re-run the `$
 - [Reactive data](docs/reactive-data.md) — the standalone `$reactive` store: `$on`, `$onAny`, `$effect`.
 - [DOM helpers](docs/dom-helpers.md) — `$`, `$$` and `$create`.
 - [Vite plugin](docs/vite-plugin.md) — importing `.html` components as bundled modules, HMR, options.
+- [Content Security Policy](docs/csp.md) — `safeEval`: running without `'unsafe-eval'`, with Vite or with no bundler at all.
 - [Dev server](docs/dev-server.md) — `npx jq79 dev`: serve and hot-reload components with no build step.
 - [Development](docs/development.md) — running tests, building, publishing releases.
 

package/dev/vite.ts

@@ -1,7 +1,11 @@
 import { readFile } from "node:fs/promises"
-import { relative } from "node:path"
+import { basename, relative } from "node:path"
 import { preprocessCSS, transformWithEsbuild } from "vite"
 import type { Plugin, ResolvedConfig } from "vite"
+// by package name rather than ../src: this file's types are emitted with dev/
+// as their root, and the generator is the runtime's own code - resolved through
+// the package's exports (external in the build, aliased to src in the tests)
+import { precompile, precompiledScript } from "jq79/precompile"
 
 // Vite plugin: import .html single-file components as modules.
 //
@@ -15,7 +19,7 @@ import type { Plugin, ResolvedConfig } from "vite"
 // with fetch instead - with one deliberate exception, a block that says it is
 // written in something else: <style lang="scss"> (or less/stylus/sass) is
 // compiled to plain CSS here, and a TypeScript script - <script lang="ts">, or
-// the <script type="text/typescript"> editors read as one - to plain JS. Such a
+// the same mark spelled <script type="text/typescript"> - to plain JS. Such a
 // component only works through the bundler; loaded with fetch() it would reach
 // the runtime uncompiled, which the runtime warns about.
 //
@@ -28,12 +32,105 @@ export interface Jq79PluginOptions {
   include?: RegExp
   // resolved absolute paths to skip even when `include` matches
   exclude?: RegExp
+  // run the app without eval, for a CSP with no 'unsafe-eval' - the value
+  // Component79.safeEval() takes, and meaning the same thing
+  // (RECORD/2026-09-23.no-unsafe-eval.md). Every component is precompiled, and
+  // its functions ship as a script of their own. `true`: those and nothing
+  // else - whatever the build couldn't see is reported, never evaluated.
+  // `{ nonce: true }`: whatever it couldn't see (a component built from a
+  // string, an edit during HMR) is built as a <script> carrying the page's nonce
+  safeEval?: boolean | { nonce?: boolean }
 }
 
 // claimed modules get this suffix so their id no longer ends in ".html" and
 // Vite's own html handling (entries, asset pipeline) leaves them alone
 const COMPONENT_QUERY = "?jq79"
 
+// safeEval. A component's precompiled functions travel as a classic script of
+// their own - Card.html.jq79.js - and not inside its module: they compile
+// under `with`, which is a SyntaxError in strict code, and every module is
+// strict. In a build the script is an asset beside the chunk; in dev the
+// server hands it out (PRECOMPILED_PATH). Either way it pushes its functions
+// onto the queue the runtime drains (see "safe eval" in src/jq79.ts).
+//
+// The component's module waits for it - a top-level await - before it builds
+// anything, through a module every component module imports. That module
+// evaluates once, so safe mode is turned on once per app, and a page with no
+// nonce is reported once rather than once per component; and it loads each
+// script once, however many modules ask. The <script> carries the page's
+// nonce when there is one, so a CSP that works by nonce admits it; under
+// `script-src 'self'` the URL is what admits it.
+//
+// Component79 is passed in rather than imported, so the module resolves
+// nothing: a bare "jq79" from a virtual importer is the one resolution that
+// would depend on how the app is laid out.
+//
+// A component built from a string *before* any .html module is imported runs
+// in the default mode; such an app calls Component79.safeEval itself. The
+// await needs a build target with top-level await in it - Vite 7 and later
+// have one by default; on Vite 5 or 6, raise build.target to es2022
+const SAFE_EVAL_ID = "virtual:jq79/safe-eval"
+const RESOLVED_SAFE_EVAL_ID = `\0${SAFE_EVAL_ID}`
+const safeEvalModule = (options: { nonce?: boolean; worker: false }) => `
+let started = null
+const loading = new Map()
+const pageNonce = () => {
+  for (const script of document.querySelectorAll("script[nonce]")) {
+    const nonce = script.nonce || script.getAttribute("nonce")
+    if (nonce) return nonce
+  }
+}
+export const safeEval = (Component79, url) => {
+  if (!started) started = Component79.safeEval(${JSON.stringify(options)}).catch(error => console.error(error))
+  let loaded = loading.get(url)
+  if (!loaded) {
+    loaded = new Promise((resolve, reject) => {
+      const script = document.createElement("script")
+      const nonce = pageNonce()
+      if (nonce) script.setAttribute("nonce", nonce)
+      script.src = url
+      script.onload = () => { script.remove(); resolve() }
+      script.onerror = () => {
+        script.remove()
+        reject(new Error("jq79: the precompiled functions at " + url + " did not load, and safeEval can't render without them"))
+      }
+      document.head.append(script)
+    })
+    loading.set(url, loaded)
+  }
+  return loaded
+}
+`
+
+// where the dev server hands out a component's precompiled script
+const PRECOMPILED_PATH = "/@jq79/precompiled.js"
+
+// the plugin's safeEval option, as what the modules pass the runtime: null
+// for off, or Component79.safeEval's own options
+const safeEvalOptions = (option: Jq79PluginOptions["safeEval"]): { nonce?: boolean } | null => {
+  if (option === undefined || option === false) return null
+  return typeof option === "object" && option !== null && option.nonce === true ? { nonce: true } : {}
+}
+
+// a scoped-form body: the runtime falls back to the `with` form when one
+// doesn't compile, so only the `with` form's failure is worth a word
+const SCOPED_BODY_RE = /^(?:let \$t;| return \()/
+
+// a component's precompiled functions, as the classic script that registers
+// them (precompiledScript, in jq79/precompile). Each is compiled here first -
+// node can, where the page may not - so the script holds only functions that
+// parse; one that doesn't ships as null, and the build says so
+const componentScript = (source: string, warn: (message: string) => void): string =>
+  precompiledScript(precompile(source), (params, body) => {
+    try {
+      new Function(...params, body)
+      return true
+    } catch (error) {
+      if (!SCOPED_BODY_RE.test(body)) warn(`${(error as Error).message}, in: ${body.length > 120 ? `${body.slice(0, 120)}…` : body}`)
+      return false
+    }
+  })
+
 // a <script> block with its attribute string, so `lang` can be read and the
 // body replaced - the same shape as STYLE_BLOCK_RE below, quote-aware so a
 // ">" inside an attribute value (`:setup="{ n = a > 1 }"`) doesn't end the tag
@@ -201,10 +298,12 @@ const compileStyleBlocks = async (
 // languages a <script lang> is compiled from. Anything else is left as written
 // for the runtime to warn about, rather than guessed at
 const TS_LANGS = new Set(["ts", "typescript"])
-// the other spelling of the same mark, and the one editors read: a component is
-// a plain .html file, not an SFC, so nothing in an IDE knows what `lang` means
-// there - embedded-script tooling picks a language from `type`, and a typed
-// block without one is linted as JavaScript. The `x-` forms are the historical
+// the other spelling of the same mark. A component is a plain .html file, not
+// an SFC, so nothing in an editor knows what `lang` means there, and each mark
+// gets half of one: VS Code's HTML language service checks a `type` of
+// text/typescript as TypeScript (and `lang="ts"` as JavaScript), while its
+// grammar colors that `type` not at all (and `lang="ts"` as JavaScript). See
+// docs/vite-plugin.md#which-mark-in-vs-code. The `x-` forms are the historical
 // spelling of the same two media types
 const TS_TYPE_RE = /^(?:text|application)\/(?:x-)?typescript$/
 
@@ -350,7 +449,9 @@ const compileScriptBlocks = async (source: string, file: string): Promise<string
 // component's markers. An instance only used as a definition has nothing to
 // re-render (nested clones can't be reached from this module), so it falls
 // back to a full reload.
-const componentModule = (source: string, include: RegExp, filename: string): string => {
+// `precompiled` is the precompiled script's URL, as a JS expression - present
+// only in safeEval mode
+const componentModule = (source: string, include: RegExp, filename: string, precompiled?: string): string => {
   const hoisted = hoistableImports(source, include)
   const imports = hoisted
     .map((spec, i) =>
@@ -361,9 +462,13 @@ const componentModule = (source: string, include: RegExp, filename: string): str
     .join("\n")
   const modulesMap = `{ ${hoisted.map((spec, i) => `${JSON.stringify(spec)}: __jq79_${i}`).join(", ")} }`
 
+  // without safeEval, the module is exactly what it always was
+  const safeEvalImport = precompiled ? `\nimport { safeEval } from "${SAFE_EVAL_ID}"` : ""
+  const safeEvalCall = precompiled ? `\nawait safeEval(Component79, ${precompiled})` : ""
+
   return `
-import { Component79 } from "jq79"
-${imports}
+import { Component79 } from "jq79"${safeEvalImport}
+${imports}${safeEvalCall}
 
 const src = ${JSON.stringify(source)}
 const modules = ${modulesMap}
@@ -397,6 +502,11 @@ ${declaredComponents(source).map(name => `export const ${name} = component.${nam
 export function jq79(options: Jq79PluginOptions = {}): Plugin {
   const include = options.include ?? /\.html$/
   const { exclude } = options
+  const safeEval = safeEvalOptions(options.safeEval)
+  // dev only: each component's precompiled script, by the id its module asks
+  // for - so the server hands out what the plugin compiled and nothing else
+  const devScripts = new Map<string, string>()
+  const devIds = new Map<string, number>()
 
   let config: ResolvedConfig | null = null
 
@@ -408,7 +518,21 @@ export function jq79(options: Jq79PluginOptions = {}): Plugin {
       config = resolved
     },
 
+    configureServer(server) {
+      if (!safeEval) return
+      server.middlewares.use((req, res, next) => {
+        const url = new URL(req.url ?? "/", "http://localhost")
+        if (!url.pathname.endsWith(PRECOMPILED_PATH)) return next()
+        const script = devScripts.get(url.searchParams.get("id") ?? "")
+        if (script === undefined) return next()
+        res.setHeader("Content-Type", "text/javascript")
+        res.setHeader("Cache-Control", "no-cache")
+        res.end(script)
+      })
+    },
+
     async resolveId(source, importer) {
+      if (source === SAFE_EVAL_ID) return RESOLVED_SAFE_EVAL_ID
       if (!importer) return null // entry points are never components
       if (source.includes("?")) return null // ?raw, ?url, ... keep their meaning
       if (!include.test(source)) return null
@@ -420,6 +544,8 @@ export function jq79(options: Jq79PluginOptions = {}): Plugin {
     },
 
     async load(id) {
+      // a Vite page's functions come from the build, so it never registers the worker
+      if (id === RESOLVED_SAFE_EVAL_ID) return safeEvalModule({ ...safeEval, worker: false })
       if (!id.endsWith(COMPONENT_QUERY)) return null
       const file = id.slice(0, -COMPONENT_QUERY.length)
 
@@ -431,7 +557,23 @@ export function jq79(options: Jq79PluginOptions = {}): Plugin {
       // shows a path the user recognizes instead of an anonymous VM script
       const filename = config ? relative(config.root, file) : file
 
-      return { code: componentModule(source, include, filename), map: null }
+      if (!safeEval) return { code: componentModule(source, include, filename), map: null }
+
+      // the component's functions, compiled after its TypeScript and styles are:
+      // the runtime compiles what reaches it, and this is what reaches it
+      const script = componentScript(source, message => this.warn(`jq79: ${filename}: ${message}`))
+      let url: string
+      if (config?.command === "serve") {
+        let devId = devIds.get(file)
+        if (devId === undefined) devIds.set(file, devId = devIds.size)
+        devScripts.set(String(devId), script)
+        // versioned, so an edit loads the new functions rather than a cached copy
+        url = JSON.stringify(`${config.base}${PRECOMPILED_PATH.slice(1)}?id=${devId}&v=${Date.now()}`)
+      } else {
+        const ref = this.emitFile({ type: "asset", name: `${basename(file)}.jq79.js`, source: script })
+        url = `import.meta.ROLLUP_FILE_URL_${ref}`
+      }
+      return { code: componentModule(source, include, filename, url), map: null }
     },
   }
 }

package/dist/dom.d.ts

@@ -1,7 +1,25 @@
-export declare function $(selector: string): Element | null;
-export declare function $(el: Element, selector: string): Element | null;
-export declare function $$(selector: string): Element[];
-export declare function $$(el: Element, selector: string): Element[];
+export type QueryOne = {
+    <K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K] | null;
+    <K extends keyof SVGElementTagNameMap>(selector: K): SVGElementTagNameMap[K] | null;
+    <E extends Element = HTMLElement>(selector: string): E | null;
+};
+export type QueryAll = {
+    <K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K][];
+    <K extends keyof SVGElementTagNameMap>(selector: K): SVGElementTagNameMap[K][];
+    <E extends Element = HTMLElement>(selector: string): E[];
+};
+export declare function $<K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K] | null;
+export declare function $<K extends keyof SVGElementTagNameMap>(selector: K): SVGElementTagNameMap[K] | null;
+export declare function $<E extends Element = HTMLElement>(selector: string): E | null;
+export declare function $<K extends keyof HTMLElementTagNameMap>(el: Element, selector: K): HTMLElementTagNameMap[K] | null;
+export declare function $<K extends keyof SVGElementTagNameMap>(el: Element, selector: K): SVGElementTagNameMap[K] | null;
+export declare function $<E extends Element = HTMLElement>(el: Element, selector: string): E | null;
+export declare function $$<K extends keyof HTMLElementTagNameMap>(selector: K): HTMLElementTagNameMap[K][];
+export declare function $$<K extends keyof SVGElementTagNameMap>(selector: K): SVGElementTagNameMap[K][];
+export declare function $$<E extends Element = HTMLElement>(selector: string): E[];
+export declare function $$<K extends keyof HTMLElementTagNameMap>(el: Element, selector: K): HTMLElementTagNameMap[K][];
+export declare function $$<K extends keyof SVGElementTagNameMap>(el: Element, selector: K): SVGElementTagNameMap[K][];
+export declare function $$<E extends Element = HTMLElement>(el: Element, selector: string): E[];
 export declare const $create: (tag: string, attrs?: Record<string, any>) => HTMLElement;
 export declare function isSafeUrl(value: string): boolean;
 export type AllowUrl = (url: URL, tag: string, attr: string) => boolean;

package/dist/html.d.ts

@@ -0,0 +1,9 @@
+export type HTMLElementNode = {
+    tag: string;
+    attrs: Record<string, string>;
+    children: HTMLNode[];
+};
+export type HTMLNode = HTMLElementNode | string;
+export declare const CHARACTER_REFERENCE_RE: RegExp;
+export declare const decodeReference: (text: string, whole: string, ref: string, offset: number, inAttribute: boolean) => string;
+export declare const parseHTML: (input: string) => HTMLNode[];