tungsten 0.4.14 → 0.5.0

package/dist/style/styleContentSxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"styleContentSxy.d.ts","sourceRoot":"","sources":["../../src/style/styleContentSxy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,EACH,KAAK,WAAW,EACnB,MAAM,mBAAmB,CAAA;AAc1B,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,eAIrE"}
+{"version":3,"file":"styleContentSxy.d.ts","sourceRoot":"","sources":["../../src/style/styleContentSxy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,EACH,KAAK,WAAW,EAEnB,MAAM,mBAAmB,CAAA;AAc1B,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,eAIrE"}

package/dist/style/styleContentSxy.js

@@ -1,5 +1,5 @@
 import { count } from 'sxy-lib/objects.js';
-import { ContentNodeElementIsHtml, ContentNodeElementIsComponent } from '../ContentNode.js';
+import { ContentNodeElementIsHtml, ContentNodeElementIsComponent, ContentNodeIsFragment } from '../ContentNode.js';
 import { warn } from '../output.js';
 import { TungstenError } from '../TungstenError.js';
 import { componentBumpClass } from '../componentClassName.js';
@@ -44,6 +44,11 @@ function processItem(element, styles, usage) {
     }
     return;
   }
+  // a fragment gets no class of its own; its children are styled as if they sat in its place
+  if (ContentNodeIsFragment(element)) {
+    processItem(element[$props].children, styles, usage);
+    return;
+  }
   debug('Element must be an element. Type: ', typeof element);
   // element is a ContentNodeElement
   let tagName;

package/dist/testing/installTestDocInit.d.ts

@@ -0,0 +1,2 @@
+export declare function installTestDocInit(): void;
+//# sourceMappingURL=installTestDocInit.d.ts.map

package/dist/testing/installTestDocInit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installTestDocInit.d.ts","sourceRoot":"","sources":["../../src/testing/installTestDocInit.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/testing/installTestDocInit.js

@@ -0,0 +1,6 @@
+// DocInit is compiled away by BabelTransformDocInit in an app build. Tests run tsc output, where
+// the global is the throwing stand-in docInit.ts installs. This makes the same split the compiled
+// form does: run the function where a document exists, else hand back the server value.
+export function installTestDocInit() {
+  globalThis.DocInit = (fn, serverValue) => typeof document !== 'undefined' ? fn() : serverValue; // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- the void overload has no server value
+}

package/dist/throwError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"throwError.d.ts","sourceRoot":"","sources":["../src/throwError.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAEnE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAErE"}
+{"version":3,"file":"throwError.d.ts","sourceRoot":"","sources":["../src/throwError.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAKnE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/throwError.js

@@ -1,7 +1,10 @@
 import { TungstenError } from './TungstenError.js';
 import { packageNameCapitalized } from './settings.js';
 export function throwError(location, message) {
-  throw new TungstenError(errorMessage(location, message));
+  const error = new TungstenError(errorMessage(location, message));
+  // V8 only (Chrome, Node): start the stack at the caller, not here. Elsewhere the frame stays.
+  Error.captureStackTrace?.(error, throwError); // eslint-disable-line @typescript-eslint/no-unnecessary-condition -- absent outside V8
+  throw error;
 }
 export function errorMessage(location, message) {
   return `${packageNameCapitalized} ${location} error: ${message}`;

package/dist/update/integrateUpdateVdom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrateUpdateVdom.d.ts","sourceRoot":"","sources":["../../src/update/integrateUpdateVdom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"integrateUpdateVdom.d.ts","sourceRoot":"","sources":["../../src/update/integrateUpdateVdom.ts"],"names":[],"mappings":"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"}

package/dist/update/integrateUpdateVdom.js

@@ -1,7 +1,7 @@
 import { IsHTMLElement } from '../DomNodes.js';
 import { DomRegion } from '../DomRegion.js';
 import { DomPointer } from '../DomPointer.js';
-import { ContentNodeComponentIsClassComponent, ContentNodeIsNonRendered, ContentNodeIsLiteral, ContentNodeIsHtml, ContentNodeIsComponent, ContentNodeIsArray, ContentNodeIsElement, ContentNodeElementHasValidKey } from '../ContentNode.js';
+import { ContentNodeComponentIsClassComponent, ContentNodeIsNonRendered, ContentNodeIsLiteral, ContentNodeIsHtml, ContentNodeIsComponent, ContentNodeIsArray, ContentNodeIsFragment, ContentNodeIsElement, ContentNodeElementHasValidKey } from '../ContentNode.js';
 import { StringIsHtmlEvent, htmlEvents } from '../htmlEvents.js';
 import { out, warn } from '../appOutput.js';
 import { getStyledContentFromFunctionComponent } from '../getStyledContentFromFunctionComponent.js';
@@ -207,6 +207,17 @@ export async function applyUpdate({
     debug('DD delete node because current node is non rendered');
     deleteNodeIfRendered(oldNode);
     return makeRenderedContentNodeNonRendered();
+  } else if (ContentNodeIsFragment(newNode)) {
+    // a fragment is its children to the reconciler; the rendered side never holds one
+    return applyUpdate({
+      tungstenElement,
+      instance,
+      newNode: newNode[$props].children,
+      oldNode,
+      domRegion,
+      domPointer,
+      parentNode
+    });
   } else if (ContentNodeIsArray(newNode)) {
     //newNode
     debug('*** Content node is array');
@@ -417,7 +428,8 @@ export async function applyUpdate({
     if (WideRenderedContentNodeIsHtml(oldNode)) {
       debug('node types', newNode[$type].toLocaleLowerCase(), oldNode[$type].toLocaleLowerCase(), newNode[$type].toLocaleLowerCase() === oldNode[$type].toLocaleLowerCase());
     }
-    if (WideRenderedContentNodeIsHtml(oldNode) && newNode[$type].toLocaleLowerCase() === oldNode[$type].toLocaleLowerCase()) {
+    if (WideRenderedContentNodeIsHtml(oldNode) && newNode[$type].toLocaleLowerCase() === oldNode[$type].toLocaleLowerCase() && oldNode[$key] === newNode[$key] // a changed, gained or lost key is a new element
+    ) {
       return updateHtmlElement(tungstenElement, instance, newNode, oldNode, domPointer);
     } else {
       //console.log('deleting node and creating html', newNode[$type], oldNode)
@@ -429,7 +441,12 @@ export async function applyUpdate({
     }
   } else if (ContentNodeIsComponent(newNode)) {
     //console.log('Comp A', WideRenderedContentNodeIsComponent(oldNode))
-    if (WideRenderedContentNodeIsComponent(oldNode) && newNode[$type] === oldNode[$type] && (oldNode[$key] !== undefined && newNode[$key] !== undefined || oldNode[$key] === newNode[$key])) {
+    if (WideRenderedContentNodeIsComponent(oldNode) && newNode[$type] === oldNode[$type] &&
+    // this code survived for years without issue
+    // but probably the simple equality check below is right
+    // (oldNode[$key] !== undefined && newNode[$key] !== undefined)
+    // || oldNode[$key] === newNode[$key]
+    oldNode[$key] === newNode[$key]) {
       //console.log('updating tu el', newNode, oldNode[$key], newNode[$key])
       // update
       return updateComponent({
@@ -639,6 +656,14 @@ async function createNode({
   if (ContentNodeIsNonRendered(newNode)) {
     debug('node is NonRendered');
     return makeRenderedContentNodeNonRendered();
+  } else if (ContentNodeIsFragment(newNode)) {
+    return createNode({
+      tungstenElement,
+      instance,
+      newNode: newNode[$props].children,
+      domPointer,
+      parentNode
+    });
   } else if (ContentNodeIsArray(newNode)) {
     debug('node is array');
     const renderedNodes = [];
@@ -1293,6 +1318,17 @@ async function updateClassComponent({
   // not fire: the component did not update.
   //console.log('old props', element.props)
   //console.log('new props', newNode[$props])
+  // an opaque class (static __opaque) renders once and then owns its dom: its parent never
+  // re-renders it, and its region is measured live because hand-added nodes change its length
+  if (element.constructor.__opaque === true) {
+    // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion -- the static declared on TungstenBaseComponent
+    markRendered(element);
+    const length = element.__domRegion?.length();
+    if (length !== undefined) {
+      domPointer.increment(length);
+      return oldNode;
+    }
+  }
   if (propsAreEqual(element.props, newNode[$props], renderedAt(element))) {
     if (tracing()) trace('SKIP', element.constructor.name, '(props unchanged since tick', renderedAt(element), ')');
     // the dom is current for these props, so the baseline moves with it -- otherwise a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tungsten",
-  "version": "0.4.14",
+  "version": "0.5.0",
   "description": "",
   "type": "module",
   "bin": {
@@ -38,6 +38,7 @@
     "@babel/preset-react": "^7.28.5",
     "@babel/preset-typescript": "^7.29.7",
     "@babel/types": "^7.29.0",
+    "@jridgewell/trace-mapping": "^0.3.31",
     "@rollup/plugin-babel": "^6.1.0",
     "@rollup/plugin-commonjs": "^28.0.9",
     "@rollup/plugin-json": "^6.1.0",

package/readme.md

@@ -2,139 +2,6 @@
 
 [Docs](https://robertsandiford.co.uk/tungsten)
 
-## Component testing
+## Agents
 
-Test-specific APIs are available from `tungsten/testing` and are not exported
-from Tungsten's main entry point. A test project supplies its own DOM
-implementation, such as happy-dom or jsdom:
-
-```tsx
-import { Window } from 'happy-dom'
-import { createTestApp } from 'tungsten/testing'
-
-describe('RootComponent', () => {
-    it('responds to a button click', async () => {
-        const window = new Window()
-        const testApp = await createTestApp(RootComponent, {
-            document: window.document as unknown as Document,
-            props: { initialName: 'Robert' },
-            location: '/',
-        })
-
-        try {
-            const button = testApp.container.querySelector('button')
-            expect(button).not.toBeNull()
-
-            button!.dispatchEvent(new window.Event('click') as unknown as Event)
-            await testApp.resolved()
-
-            expect(testApp.container.textContent).toContain('Robert')
-        } finally {
-            await testApp.unmount()
-        }
-    })
-})
-```
-
-The casts are only needed when a DOM package publishes types which are not
-structurally compatible with the TypeScript DOM library version used by the
-test project.
-
-`createTestApp()` completes the initial client render before returning.
-`resolved()` subsequently waits for Tungsten updates, DOM reconciliation,
-lifecycle-triggered updates, and promises returned by registered event
-handlers. It does not wait for unrelated timers, network requests, or promises
-which the application has not returned to Tungsten.
-
-An automatically created container is appended to the supplied document body
-and removed by `unmount()`. A caller-supplied container must be empty; it is
-emptied but retained during unmount.
-
-Registered stores are created independently for each test application. Use
-`testStore()` to initialize one before the root component starts:
-
-```ts
-import { createTestApp, testStore } from 'tungsten/testing'
-
-const testApp = await createTestApp(RootComponent, {
-    document,
-    stores: [testStore(userStore, store => {
-        store.user.set(mockUser)
-    })],
-})
-```
-
-Tests containing Tungsten JSX must be compiled through `tungsten compile` so
-they use Tungsten's JSX runtime and application transforms.
-
-## Preparing code for tests
-
-Run a one-shot development compilation without starting a server:
-
-```sh
-tungsten compile
-```
-
-By default this compiles JavaScript (including JSX and Tungsten's Babel
-transforms), stylesheets, client support files, assets, and public files into
-`.tungsten/dev`.
-Each selected target's existing generated output is cleaned before the initial
-compilation, including when watch mode is used. Pass `--no-clean` to preserve
-existing output.
-
-Use `--output` to select an independent output root. The layout below that root
-is the same as `.tungsten/dev`, including `code`, `.client`, `.static`,
-`.assets`, `.public`, `.componentCss`, and `.packages`:
-
-```sh
-tungsten compile --output .tungsten/test
-tungsten compile --output .tungsten/test --watch
-```
-
-Cleaning and generated package-cache data are scoped to the selected output.
-Limit the work with one or more options:
-
-```sh
-tungsten compile --js
-tungsten compile --css
-tungsten compile --client
-tungsten compile --assets
-tungsten compile --public
-tungsten compile --js --css
-```
-
-`--all` explicitly selects all five targets.
-
-Add `--watch` to keep the JavaScript, stylesheet, asset, and/or public-file
-compiler running after the initial pass. Client support files are still
-generated once:
-
-```sh
-tungsten compile --watch
-tungsten compile --js --watch
-```
-
-For process orchestration, `--ready-file <file>` writes a small JSON file only
-after the initial compilation succeeds. A failed JavaScript watch cycle removes
-the file, and a later successful cycle recreates it. `--quiet` suppresses
-per-file transformation messages while retaining errors and cycle status:
-
-```sh
-tungsten compile --watch --output .tungsten/test \
-  --ready-file .tungsten/test.ready --quiet
-```
-
-## Preserving package imports in selected files
-
-Use `skipPackageCompilation` in `tungsten.config.js` for files that should be
-transformed and emitted without Tungsten traversing or copying their package
-dependencies. Bare package imports in matching files are left unchanged:
-
-```js
-export default {
-    skipPackageCompilation: '**/*.domTest.js'
-}
-```
-
-The option accepts one glob or an array of globs. Patterns match the actual
-JavaScript files received by Tungsten; extensions are not translated.
+If you are an agent, read [AGENTS.md](AGENTS.md)

package/types/assets.d.ts

@@ -0,0 +1,21 @@
+//// Importing a stylesheet gives the url of the compiled file, inserted at build. A string so the
+//// value is a valid ContentNode and can be passed as children: `<Stylesheet>{globalStyles}</Stylesheet>`
+//// No import or export in this file: as a script these are ambient declarations, where in a
+//// module they would be augmentations, which cannot add exports
+
+declare module '*.css' {
+    const href: string
+    export default href
+}
+declare module '*.sass' {
+    const href: string
+    export default href
+}
+declare module '*.scss' {
+    const href: string
+    export default href
+}
+declare module '*.less' {
+    const href: string
+    export default href
+}

package/types/index.d.ts

@@ -1,6 +1,15 @@
 
 /* eslint-disable no-var */
 
+// the stylesheet module declarations live in a script file: this one is a module, and a
+// `declare module '*.css'` here would augment the app's own '*.css' declaration, which cannot add exports.
+// A reference, as an import of a script file is refused
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="./assets.d.ts" />
+// Disposable and Symbol.dispose appear in the shipped types (component using(), browser storage), and in
+// TS 6 that lib comes only with ESNext - so bring it in here rather than require it of every app's lib list
+/// <reference lib="esnext.disposable" />
+
 import { CssNames } from 'tungsten/CssNames.js'
 
 //export type { JSX } from './jsx/jsx.d.js'
@@ -12,12 +21,27 @@ declare global {
     var Scss: (style: TemplateStringsArray) => CssNames
     var ReactZoneScss: (style: TemplateStringsArray) => CssNames
     //var Less: (style: TemplateStringsArray) => CssNames
+
+    //// Rewritten at build by BabelTransformDocInit: fn is inlined into the document head and runs
+    //// there before <body>; the call becomes a read of its result (the server gets serverValue).
+    //// fn must be self-contained - only globals like document and localStorage exist in the head.
+    var DocInit: {
+        <T>(fn: () => T, serverValue: NoInfer<T>): T
+        (fn: () => void): void
+    }
 }
 
+//// Apps fill these by declaration merging in their env module: `interface TungstenPrivateEnv extends PrivateEnv {}`.
+//// Empty here on purpose: a base that extended the core env types would collide with an app whose schema
+//// makes a core field required (TS2320). Tungsten's own reads of the core fields come from src/env/Interfaces.ts
+/* eslint-disable @typescript-eslint/no-empty-object-type */
 declare global {
+    interface TungstenPrivateEnv {}
+    interface TungstenPublicEnv {}
     var tungstenPrivateEnv: TungstenPrivateEnv
     var tungstenPublicEnv: TungstenPublicEnv
 }
+/* eslint-enable @typescript-eslint/no-empty-object-type */
 
 //// In dev, cjsHelpers.ts installs a partial `process` on the browser global so that converted
 //// CommonJS packages can read process.env.NODE_ENV. It flags itself with __tungstenCjsShim so
@@ -36,33 +60,4 @@ declare global {
 //     var __T_CurrentElement: TElement // eslint-disable-line no-var
 // }
 
-//// Allow importing css files (treated as exporting the url of the final stylesheet file
-//// as a string, which is actually magically inserted by compilation)
-//// A string is used so that the value is a valid ContentNode and can be passed as children,
-//// e.g. `<Stylesheet>{globalStyles}</Stylesheet>`
-//// For some reason these declarions are recognised, but TS complains unless the project folder
-//// contains an additional `declare module '*.sass'` entry
-
-// declare module '*.css'
-// declare module '*.sass'
-// declare module '*.scss'
-// declare module '*.less'
-
-declare module '*.css' {
-    const href: string
-    export default href
-}
-declare module '*.sass' {
-    const href: string
-    export default href
-}
-declare module '*.scss' {
-    const href: string
-    export default href
-}
-declare module '*.less' {
-    const href: string
-    export default href
-}
-
 export {}

package/types/jsx/html.d.ts

@@ -967,7 +967,6 @@ export interface LiHTMLAttributes<T, BO extends object> extends HTMLAttributes<T
 export interface LinkHTMLAttributes<T> extends HTMLAttributes<T> {
     as?: string | undefined;
     crossOrigin?: 'anonymous' | 'use-credentials' | '' | undefined;
-    fetchpriority?: 'high' | 'low' | 'auto';
     href?: string | undefined;
     hrefLang?: string | undefined;
     integrity?: string | undefined;

package/types/jsx/html.global.d.ts

@@ -15,7 +15,6 @@ interface WheelEvent extends Event { }
 interface EventTarget { }
 interface Document { }
 interface DataTransfer { }
-interface StyleMedia { }
 
 interface Element { }
 interface DocumentFragment { }

package/types/jsx/html.values.d.ts

@@ -7,7 +7,6 @@ export type Booleanish = boolean | 'true' | 'false'
 // ----------------------------------------------------------------------
 
 export interface AbstractView {
-    styleMedia: StyleMedia;
     document: Document;
 }
 

package/types/jsx/jsx.d.ts

@@ -1,5 +1,5 @@
 
-import type { ContentNode, ContentNodeComponent } from 'tungsten/ContentNode.js'
+import type { ContentNode, ContentNodeElement, ContentNodeType } from 'tungsten/ContentNode.js'
 import { TungstenBaseComponent } from 'tungsten/Components.jsx'
 import type { FunctionComponent } from 'tungsten/FunctionComponent.js'
 import type { TungstenRef } from 'tungsten/createRef.js'
@@ -324,16 +324,16 @@ export interface TungstenIntrinsicElements {
     view: SVGProps<SVGViewElement>;
 }
 
-type IntrinsicElement = TungstenIntrinsicElements[keyof TungstenIntrinsicElements]
-
-type TungstenElementType = string | JSXElementConstructor<any>;
-export type TungstenElement = IntrinsicElement | ContentNodeComponent
-export interface TungstenElementAttributesProperty { props: {}; } // eslint-disable-line @typescript-eslint/ban-types
-export interface TungstenElementChildrenAttribute { children: {}; } // eslint-disable-line @typescript-eslint/ban-types
+export type TungstenElement = ContentNodeElement
+export interface TungstenElementAttributesProperty { props: {}; } // eslint-disable-line @typescript-eslint/no-empty-object-type
+export interface TungstenElementChildrenAttribute { children: {}; } // eslint-disable-line @typescript-eslint/no-empty-object-type
 
 declare global {
     namespace JSX {
-        export type Element = ContentNode // ContentNode allows an array. Use Core because Element is exclusive of an array of Elements
+        export type Element = ContentNodeElement // every JSX expression is an element node - a fragment included
+        // what may stand as a tag. Declared (TS 5.1+) so a component's return type is checked against
+        // ContentNode through its own signature, not against Element
+        export type ElementType = ContentNodeType
         export interface ElementAttributesProperty extends TungstenElementAttributesProperty {}
         export interface ElementChildrenAttribute extends TungstenElementChildrenAttribute {}
         export type ElementClass = TungstenBaseComponent<any, any> | FunctionComponent<any, any>

package/vendor/manifest.json

@@ -1,7 +1,7 @@
 {
     "lockfile": {
-        "size": 246952,
-        "mtimeMs": 1788803027627.8281
+        "size": 247038,
+        "mtimeMs": 1789221974883.9106
     },
     "specifiers": {
         "@babel/core": "babel-core",