jq79 0.7.1 → 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.
 //
@@ -12,11 +16,12 @@ import type { Plugin, ResolvedConfig } from "vite"
 // thing `await Component79.fetch(url)` resolves to, but bundled at build time
 // instead of fetched at runtime. The component source is inlined verbatim, so
 // a file keeps working unchanged if it's ever served from public/ and loaded
-// with fetch instead - with one deliberate exception, `lang`: <style lang="scss">
-// (or less/stylus/sass) is compiled to plain CSS here, and <script lang="ts"> to
-// plain JS. A component using `lang` therefore only works through the bundler;
-// loaded with fetch() it would reach the runtime uncompiled, which the runtime
-// warns about.
+// 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 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.
 //
 // Only .html files imported from other modules are claimed; entry points
 // (index.html) have no importer and imports carrying an explicit query
@@ -27,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
@@ -152,6 +250,14 @@ const declaredComponents = (source: string): string[] => {
 // inside one doesn't end the tag early
 const STYLE_BLOCK_RE = /<style((?:"[^"]*"|'[^']*'|[^>"'])*)>([\s\S]*?)<\/style\s*>/gi
 const LANG_ATTR_RE = /\blang\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i
+const TYPE_ATTR_RE = /\btype\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/i
+
+// one attribute's value out of a tag's attribute string, whichever way it was
+// quoted - null when the attribute isn't there at all
+const attrValue = (attrs: string, re: RegExp): string | null => {
+  const found = attrs.match(re)
+  return found ? found[1] ?? found[2] ?? found[3] : null
+}
 
 // compiles <style lang="scss|less|styl|sass"> blocks to plain CSS with Vite's
 // own preprocessing (the same call @vitejs/plugin-vue makes), so the runtime
@@ -170,9 +276,8 @@ const compileStyleBlocks = async (
   const blocks = [...source.matchAll(STYLE_BLOCK_RE)]
   const compiled = await Promise.all(
     blocks.map(async ([, attrs, content]) => {
-      const lang = attrs.match(LANG_ATTR_RE)
-      if (!lang) return null
-      const extension = lang[1] ?? lang[2] ?? lang[3]
+      const extension = attrValue(attrs, LANG_ATTR_RE)
+      if (extension === null) return null
       const result = await preprocessCSS(content, `${file}.${extension}`, config)
       result.deps?.forEach(addWatchFile)
       return { attrs: attrs.replace(LANG_ATTR_RE, "").trimEnd(), css: result.code }
@@ -193,6 +298,26 @@ 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. 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$/
+
+// what marks a script block as TypeScript, given back as the attribute to drop
+// from the emitted tag - the block is compiled to JS, so the mark goes with the
+// types whichever one carried it. A `lang` answers on its own: `lang="coffee"`
+// is a language this plugin doesn't compile, and reading `type` past it would
+// compile a block the author said was something else
+const typescriptAttr = (attrs: string): RegExp | null => {
+  const lang = attrValue(attrs, LANG_ATTR_RE)
+  if (lang !== null) return TS_LANGS.has(lang.trim().toLowerCase()) ? LANG_ATTR_RE : null
+  const type = attrValue(attrs, TYPE_ATTR_RE)
+  return type !== null && TS_TYPE_RE.test(type.trim().toLowerCase()) ? TYPE_ATTR_RE : null
+}
 
 type ViteTransform = (code: string, id: string, options?: unknown) => Promise<{ code: string }>
 
@@ -231,10 +356,10 @@ const SETUP_ATTR_RE = /(:setup\s*=\s*)(?:"([^"]*)"|'([^']*)')/i
 const SIGNATURE_MARKER = "__jq79_signature__"
 
 // a component's props signature lives in the `:setup` *attribute*, not in the
-// script body, so the body's transform never sees it - and `lang="ts"` has to
-// mean the same thing on both halves of the block, or a typed signature either
-// survives into a component the plugin just promised was JS or, for `_: Props`,
-// stops reading as a signature at all.
+// script body, so the body's transform never sees it - and the TypeScript mark
+// has to mean the same thing on both halves of the block, or a typed signature
+// either survives into a component the plugin just promised was JS or, for
+// `_: Props`, stops reading as a signature at all.
 //
 // It goes through the same transform as everything else, wrapped as a
 // parameter list, rather than being cut with a scanner of its own: the
@@ -259,12 +384,13 @@ const stripSignatureTypes = async (value: string, file: string): Promise<string>
 // already wrote `&quot;`
 const quoteAttrValue = (value: string) => value.replace(/"/g, "&quot;")
 
-// compiles <script lang="ts"> blocks to plain JS, so the runtime only ever sees
+// compiles TypeScript script blocks to plain JS, so the runtime only ever sees
 // JS - the same deal <style lang="scss"> gets, for a sharper reason. The setup
 // scanner is not a parser: `let count: number = 0` reaching it is not a syntax
 // error but a labeled statement that assigns to `number`, so it runs and leaves
-// `count` undeclared. `lang` is dropped from the emitted tag and every other
-// attribute (`:setup`, `:mounted`) is left as written.
+// `count` undeclared. Whichever attribute marked the block (`lang="ts"` or
+// `type="text/typescript"`) is dropped from the emitted tag and every other one
+// (`:setup`, `:mounted`) is left as written.
 //
 // This runs before hoistableImports reads the source, so an `import type`
 // specifier is already gone by the time the plugin decides what to bundle
@@ -272,11 +398,10 @@ const compileScriptBlocks = async (source: string, file: string): Promise<string
   const blocks = [...source.matchAll(SCRIPT_BLOCK_RE)]
   const compiled = await Promise.all(
     blocks.map(async ([, attrs, content]) => {
-      const lang = attrs.match(LANG_ATTR_RE)
-      const name = (lang?.[1] ?? lang?.[2] ?? lang?.[3])?.toLowerCase()
-      if (!name || !TS_LANGS.has(name)) return null
+      const marker = typescriptAttr(attrs)
+      if (!marker) return null
 
-      let rest = attrs.replace(LANG_ATTR_RE, "").trimEnd()
+      let rest = attrs.replace(marker, "").trimEnd()
       const setup = rest.match(SETUP_ATTR_RE)
       if (setup) {
         const signature = await stripSignatureTypes(setup[2] ?? setup[3], `${file}.signature.ts`)
@@ -324,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) =>
@@ -335,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}
@@ -371,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
 
@@ -382,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
@@ -394,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)
 
@@ -405,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[];