@relicloops/cathode 2.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,390 @@
+# Cathode
+
+Formerly **NeonJSX** -- renamed to align with the Cathode -> Phosphor ecosystem.
+
+Cathode is a tiny JSX runtime with a straightforward render pipeline. It turns
+JSX into lightweight virtual nodes, then renders them to real DOM nodes with a
+single pass. No diffing, no reconciliation, no hooks, just the essentials.
+
+## Features
+- Small, dependency-free runtime
+- Classic JSX pragma support (`h` / `Fragment`)
+- Simple DOM renderer (`render`)
+- CSS loading with browser cache optimization (`css`)
+- Dynamic component loading (`lazy` / `Suspense`)
+- TypeScript-friendly, ESM-first
+
+## Compile TSX/JSX (your app)
+Cathode is a runtime only. You bring the compiler, and it should use the classic
+JSX transform with `h` and `Fragment`.
+
+## Complete example (esbuild)
+A full, minimal app you can copy into a new directory.
+
+Project layout:
+```
+cathode-example/
+  package.json
+  tsconfig.json
+  src/
+    index.tsx
+  public/
+    index.html
+    app.css
+```
+
+`package.json`:
+```json
+{
+  "name": "cathode-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/index.tsx --bundle --format=esm --platform=browser --jsx=transform --jsx-factory=h --jsx-fragment=Fragment --outfile=public/app.js"
+  },
+  "dependencies": {
+    "@relicloops/cathode": "^2.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.2"
+  }
+}
+```
+
+`tsconfig.json` (editor types only):
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "@relicloops/cathode",
+    "strict": true
+  },
+  "include": ["src"]
+}
+```
+
+`src/index.tsx`:
+```ts
+import { render, css } from '@relicloops/cathode';
+
+const App = () => {
+  css('./app.css');  // URL-based, browser cached
+  css('.highlight { color: blue; }', { inline: true });  // Inline CSS
+  return (
+    <main>
+      <h1>Cathode</h1>
+      <p className="highlight">Runtime-only JSX, compiled by your toolchain.</p>
+    </main>
+  );
+};
+
+render(<App />, document.getElementById('root')!);
+```
+
+`public/index.html`:
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Cathode Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>
+```
+
+`public/app.css`:
+```css
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: system-ui, sans-serif;
+  background: #1a1a2e;
+  color: #eee;
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+main {
+  text-align: center;
+}
+
+h1 {
+  font-size: 2.5rem;
+  margin-bottom: 0.5rem;
+}
+```
+
+Run it:
+```bash
+npm install
+npm run build
+```
+
+For a complete example with lazy loading, Suspense, trigger-based loading patterns, and animated spinners, see [docs/README.md](docs/README.md).
+
+To download only the example:
+```bash
+git clone --depth 1 --filter=blob:none --sparse https://github.com/relicloops/cathode.git
+cd cathode
+git sparse-checkout set docs
+```
+
+## API
+
+### `h(type, props, ...children)`
+Creates a virtual node. This is the JSX factory function.
+
+### `Fragment`
+Collects children without adding an extra DOM element.
+
+### `render(node, parent)`
+Initial mount only. Clears the parent and appends the rendered DOM tree.
+Use this when you bootstrap the app at first page load and you want the
+root container to represent the whole application.
+
+Why keep `render()`?
+- It is synchronous and simple, which is ideal for the first mount.
+- It communicates that this is the primary app root, not a dynamic insert.
+- It keeps existing examples and mental models for app startup intact.
+
+For dynamic updates inside existing DOM, use `inject()` or `mount()`.
+
+### `mount(node, parent)`
+Async root mount with an explicit lifecycle handle. `mount()` is the
+modern, explicit alternative to `render()` when you want control over
+cleanup and future lifecycle capabilities.
+
+```ts
+const root = await mount( <App />, document.getElementById( 'root' )! );
+```
+
+What it does today:
+- Performs a `render()` into the container (replace mode).
+- Returns a handle with `unmount()` and `cleanup()` methods.
+- Tracks that the container is a mounted root.
+
+Why use it:
+- Clear intent: "this is a mounted root I may later tear down".
+- Safer teardown: you can unmount predictably, even across routes or hot reloads.
+- Forward compatible: the handle gives us space to add updates or teardown hooks.
+
+### `unmount(parent)`
+Async teardown of a mounted root container.
+
+```ts
+await unmount( document.getElementById( 'root' )! );
+```
+
+Current behavior:
+- Clears the container.
+- Removes the container from the internal mounted registry.
+
+### `cleanup(parent)`
+Async cleanup alias for `unmount()`. This is the semantic "end of lifecycle"
+operation you can call when you want to ensure the container is empty and
+the mount is discarded.
+
+```ts
+await cleanup( document.getElementById( 'root' )! );
+```
+
+Why both `unmount` and `cleanup`?
+- `unmount()` is lifecycle terminology that matches other UI runtimes.
+- `cleanup()` reads more like a finalization step, especially in async flows.
+
+### `inject(node, parent, options?)`
+Async injection for dynamic content inside an existing DOM container.
+This is ideal for spinners, toasts, dialogs, or any UI that lives inside
+an already-mounted part of the page.
+
+```ts
+await inject( <Spinner />, contentEl, { mode: 'append' } );
+```
+
+Modes:
+- `replace` (default): same DOM behavior as `render()` but without implying
+  this is the root app mount.
+- `append`: inserts the rendered nodes after the current children.
+- `prepend`: inserts the rendered nodes before the current children.
+
+Notes:
+- `inject()` is async so the API can evolve (cleanup hooks, async rendering,
+  or future diffing) without breaking your call sites.
+- Use `eject()` to remove injected content when you are done.
+
+### `eject(parent)`
+Async cleanup for injected content. Clears the parent container.
+
+```ts
+await eject( contentEl );
+```
+
+### How the APIs fit together
+Think of the DOM in two layers: root app mounts and local injections.
+
+Root mount (app lifecycle):
+- Use `render()` for the simplest initial boot.
+- Use `mount()` if you want explicit teardown and a returned handle.
+- Use `unmount()` or `cleanup()` to remove the root app.
+
+Local injection (dynamic UI inside the app):
+- Use `inject()` to place content inside an existing DOM container.
+- Use `eject()` to clear that container.
+
+This split keeps the intent clear:
+- `render()`/`mount()` communicate "this is the app root".
+- `inject()` communicates "this is a dynamic insertion".
+
+### `css(urlOrContent, options?)`
+Loads CSS on first component render with deduplication.
+
+```ts
+css('/styles/button.css');                    // URL-based (browser cached)
+css('.btn { color: red; }', { inline: true }); // Inline CSS
+```
+
+- **URL mode**: Injects `<link rel="stylesheet">` into `<head>`
+- **Inline mode**: Injects `<style>` into `<head>` (pass `{ inline: true }`)
+- **Deduplication**: Same CSS is only loaded once across all components
+- **Status attribute**: `data-cathode-css-status` = `loading` | `loaded` | `error`
+- **SSR safe**: No-op when `document` is undefined
+
+### `lazy(loader)`
+Wraps a dynamic import for on-demand component loading. The component loads automatically when rendered.
+
+```ts
+import { lazy, Suspense, render } from '@relicloops/cathode';
+
+const Dashboard = lazy(() => import('./Dashboard.js'));
+
+const App = () => (
+  <Suspense fallback={<p>Loading...</p>}>
+    <Dashboard userId={123} />
+  </Suspense>
+);
+
+render(<App />, document.getElementById('root')!);
+```
+
+- **Caching**: Same loader returns the same component instance
+- **Exports**: Accepts a default export, a direct function module, or a single named export
+- **SSR safe**: No-op when `document` is undefined
+- **Preloading**: Call `Dashboard.awake()` to preload before render
+
+### `lazyOnDemand(loader)`
+Like `lazy()`, but requires explicit triggering - the component won't load until you call `awake()`.
+
+```ts
+import { lazyOnDemand, Suspense } from '@relicloops/cathode';
+
+const Settings = lazyOnDemand(() => import('./Settings.js'));
+
+const App = () => (
+  <>
+    <button onClick={() => Settings.awake()}>Load Settings</button>
+    <Suspense fallback={<p>Loading...</p>}>
+      <Settings />
+    </Suspense>
+  </>
+);
+```
+
+Note: `__load()` is deprecated but still available for backward compatibility. Prefer `awake()`.
+
+### Lazy Loading Helpers
+
+**`lazyOnHover(component)`** - Load on mouse enter:
+```ts
+import { lazyOnDemand, lazyOnHover } from '@relicloops/cathode';
+
+const Dashboard = lazyOnDemand(() => import('./Dashboard.js'));
+const hoverProps = lazyOnHover(Dashboard);
+
+<a href="/dashboard" {...hoverProps}>Dashboard</a>
+```
+
+**`lazyAfterDelay(component, ms)`** - Load after timeout:
+```ts
+import { lazyOnDemand, lazyAfterDelay } from '@relicloops/cathode';
+
+const Analytics = lazyOnDemand(() => import('./Analytics.js'));
+lazyAfterDelay(Analytics, 3000); // Load after 3 seconds
+```
+
+**`lazyWhenIdle(component, timeout?)`** - Load when browser is idle:
+```ts
+import { lazyOnDemand, lazyWhenIdle } from '@relicloops/cathode';
+
+const ChatWidget = lazyOnDemand(() => import('./ChatWidget.js'));
+lazyWhenIdle(ChatWidget); // Load during idle time
+```
+
+**`LazyOnVisible`** - Load when scrolled into view:
+```ts
+import { lazyOnDemand, LazyOnVisible } from '@relicloops/cathode';
+
+const Footer = lazyOnDemand(() => import('./Footer.js'));
+
+<LazyOnVisible
+  component={Footer}
+  fallback={<div style="height: 200px">Scroll to load footer</div>}
+  rootMargin="200px"
+/>
+```
+
+### `Suspense`
+Shows a fallback while lazy components inside are loading. Fallback can be a VNode, string, or number.
+
+```ts
+<Suspense fallback={<div>Loading...</div>}>
+  <LazyComponent />
+</Suspense>
+```
+
+Multiple lazy components share the same fallback:
+```ts
+const Chart = lazy(() => import('./Chart.js'));
+const Table = lazy(() => import('./Table.js'));
+
+<Suspense fallback={<div class="skeleton" />}>
+  <Chart />
+  <Table />
+</Suspense>
+```
+
+### `ErrorBoundary`
+Catches errors in children and displays a fallback.
+
+```ts
+import { ErrorBoundary } from '@relicloops/cathode';
+
+<ErrorBoundary fallback={(error) => <p>Error: {error.message}</p>}>
+  <Suspense fallback={<p>Loading...</p>}>
+    <Dashboard />
+  </Suspense>
+</ErrorBoundary>
+```
+
+### Types
+- `ComponentType<P>`: Component function signature for typing props and returns.
+
+## Notes
+- This renderer clears the target container on each `render`.
+- Event handlers use `onClick`, `onInput`, etc. (lowercased when assigned).
+
+## License
+Apache-2.0

package/index.js

@@ -0,0 +1,9 @@
+export * from './lib/runtime.js';
+export { inject } from './lib/inject.js';
+export { eject } from './lib/eject.js';
+export { mount, unmount, cleanup } from './lib/mount.js';
+export { css } from './lib/css.js';
+export { lazy, lazyOnDemand } from './lib/lazy.js';
+export { lazyOnHover, lazyAfterDelay, lazyWhenIdle, LazyOnVisible } from './lib/lazy-helpers.js';
+export { Suspense } from './lib/suspense.js';
+export { ErrorBoundary } from './lib/error-boundary.js';

package/jsx-dev-runtime.js

@@ -0,0 +1 @@
+export * from './jsx-runtime.js';

package/jsx-runtime.js

@@ -0,0 +1,20 @@
+import { h, Fragment } from './lib/runtime.js';
+export { Fragment };
+function toChildArray(children) {
+    if (children === undefined || children === null) {
+        return [];
+    }
+    if (Array.isArray(children)) {
+        return children;
+    }
+    return [children];
+}
+export function jsx(type, props, key) {
+    const { children, ...rest } = props ?? {};
+    if (key !== undefined) {
+        rest.key = key;
+    }
+    return h(type, rest, ...toChildArray(children));
+}
+export const jsxs = jsx;
+export const jsxDEV = jsx;

package/lib/css.js

@@ -0,0 +1,40 @@
+const loadedCSS = new Set();
+function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
+    }
+    return hash.toString(36);
+}
+export function css(urlOrContent, options) {
+    const isInline = options?.inline ?? false;
+    const key = isInline ? `inline:${hashString(urlOrContent)}` : urlOrContent;
+    if (loadedCSS.has(key)) {
+        return;
+    }
+    loadedCSS.add(key);
+    if (typeof document === 'undefined') {
+        return;
+    }
+    if (isInline) {
+        const style = document.createElement('style');
+        style.setAttribute('data-cathode-css', key);
+        style.setAttribute('data-cathode-css-status', 'loaded');
+        style.textContent = urlOrContent;
+        document.head.appendChild(style);
+    }
+    else {
+        const link = document.createElement('link');
+        link.rel = 'stylesheet';
+        link.href = urlOrContent;
+        link.setAttribute('data-cathode-css', key);
+        link.setAttribute('data-cathode-css-status', 'loading');
+        link.addEventListener('load', () => {
+            link.setAttribute('data-cathode-css-status', 'loaded');
+        }, { once: true });
+        link.addEventListener('error', () => {
+            link.setAttribute('data-cathode-css-status', 'error');
+        }, { once: true });
+        document.head.appendChild(link);
+    }
+}

package/lib/eject.js

@@ -0,0 +1,3 @@
+export async function eject(parent) {
+    parent.innerHTML = '';
+}

package/lib/error-boundary.js

@@ -0,0 +1,10 @@
+export function ErrorBoundary(props) {
+    return {
+        type: '__error_boundary__',
+        props: {
+            fallback: props.fallback,
+            children: props.children
+        },
+        children: Array.isArray(props.children) ? props.children : [props.children]
+    };
+}