@navette-js/wire 0.0.0-stage → 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NavetteJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @navette-js/wire
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server-side runtime compatible with Livewire 3 for Node.js and Express.
+
+Part of [Navette](https://github.com/NavetteJS/navette), admin panels for Node.js. Start a project with `npm create navette@latest`, or install the framework with `npm install @navette-js/panels`.
+
+**Beta:** the API may still change between beta releases.
+
+License: MIT. Third-party notices: see `THIRD-PARTY-NOTICES.md` where present.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,12 @@
+# Third-party notices
+
+Navette is an independent project, not affiliated with or endorsed by the Filament, Livewire or Heroicons projects. It reuses the following works, each under its own license; the full license texts ship next to the files they cover.
+
+| Work | Used for | License | License file |
+|---|---|---|---|
+| [Filament](https://github.com/filamentphp/filament) © Filament | HTML markup derived from its Blade views, compiled CSS and JavaScript (`@navette-js/panels/dist/filament`), English translations (`@navette-js/support/data`) | MIT | `packages/panels/dist/FILAMENT-LICENSE.md` |
+| [Livewire](https://github.com/livewire/livewire) © Caleb Porzio | Client script `livewire.js` (`@navette-js/wire/vendor`); the server runtime follows its protocol | MIT | `packages/wire/vendor/LIVEWIRE-LICENSE.md` |
+| [Heroicons](https://github.com/tailwindlabs/heroicons) | SVG icons (`@navette-js/support/icons`) | MIT | `packages/support/icons/HEROICONS-LICENSE.md` |
+| [Inter](https://github.com/rsms/inter) © The Inter Project Authors | Default font files (`@navette-js/panels/dist/filament/fonts`) | SIL Open Font License 1.1 | `packages/panels/dist/filament/fonts/INTER-LICENSE.txt` |
+
+Runtime dependencies installed from npm (Express, Knex, Objection, better-sqlite3, Tiptap, EJS, Busboy…) keep their own licenses.

package/lib/express.d.ts

@@ -0,0 +1,15 @@
+import type { Request, Response, Router } from 'express';
+import { type WireRuntime } from './index.ts';
+/** Double-submit CSRF token: an HttpOnly cookie, plus the token livewire.js sends back in the body (`_token`). */
+export declare function csrfToken(req: Request, res: Response): string;
+/** Checks the submitted token (body or form field) against the cookie, in constant time. */
+export declare function verifyCsrf(req: Request, token: unknown): boolean;
+export declare function wireRouter(runtime: WireRuntime, prefix?: string, makeContext?: (req: Request, res: Response) => unknown | Promise<unknown>, 
+/** Wraps the handling in a request context and can enrich the response (notifications…). */
+around?: (ctx: any, req: Request, res: Response, handle: () => Promise<any>) => Promise<any>, 
+/** Authorizes a file upload (e.g. signed-in user). Without it, anyone holding a signed URL and the CSRF token can upload. */
+canUpload?: (ctx: any) => boolean | Promise<boolean>): Router;
+/** `<script>` tag that loads livewire.js with its CSRF token and endpoint URLs. */
+export declare function wireScripts(req: Request, res: Response, prefix?: string): string;
+/** Styles livewire.js expects (loading states, cloak, progress bar); place them in `<head>`. */
+export declare function wireStyles(progressBarColor?: string): string;

package/lib/express.js

@@ -0,0 +1,92 @@
+// Express integration: serves the bundled livewire.js and exposes the CSRF-protected update and upload endpoints.
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { WireError } from "./index.js";
+const vendor = (f) => fileURLToPath(new URL(`../vendor/${f}`, import.meta.url));
+const versionHash = JSON.parse(readFileSync(vendor('manifest.json'), 'utf8'))['/livewire.js'];
+const COOKIE = 'navette_csrf';
+const readCookie = (req, name) => (req.headers.cookie ?? '').split(';').map((c) => c.trim().split('=')).find(([k]) => k === name)?.[1];
+/** Double-submit CSRF token: an HttpOnly cookie, plus the token livewire.js sends back in the body (`_token`). */
+export function csrfToken(req, res) {
+    let token = readCookie(req, COOKIE) ?? res.locals.navetteCsrf;
+    if (!token) {
+        token = randomBytes(24).toString('base64url');
+        res.cookie(COOKIE, token, { httpOnly: true, sameSite: 'lax', secure: req.secure === true });
+        res.locals.navetteCsrf = token;
+    }
+    return token;
+}
+/** Checks the submitted token (body or form field) against the cookie, in constant time. */
+export function verifyCsrf(req, token) {
+    const cookie = Buffer.from(readCookie(req, COOKIE) ?? ''), sent = Buffer.from(String(token ?? ''));
+    return cookie.length > 0 && cookie.length === sent.length && timingSafeEqual(cookie, sent);
+}
+export function wireRouter(runtime, prefix = '/livewire', makeContext = (req, res) => ({ req, res }), 
+/** Wraps the handling in a request context and can enrich the response (notifications…). */
+around = (_ctx, _req, _res, handle) => handle(), 
+/** Authorizes a file upload (e.g. signed-in user). Without it, anyone holding a signed URL and the CSRF token can upload. */
+canUpload = () => true) {
+    const router = express.Router();
+    router.get(`${prefix}/livewire.js`, (_req, res) => {
+        res.type('application/javascript').set('Cache-Control', 'public, max-age=31536000, immutable').sendFile(vendor('livewire.js'));
+    });
+    router.post(`${prefix}/update`, express.json({ limit: '2mb' }), async (req, res) => {
+        try {
+            if (!verifyCsrf(req, req.body?._token))
+                throw new WireError(419, 'Invalid CSRF token.');
+            const ctx = await makeContext(req, res);
+            res.json(await around(ctx, req, res, () => runtime.handle(req.body, ctx)));
+        }
+        catch (e) {
+            const status = e instanceof WireError ? e.status : 500;
+            if (status === 500)
+                console.error(e);
+            else if (process.env.NODE_ENV !== 'production')
+                console.warn(`[wire] ${status} ${e.message} — calls=${JSON.stringify(req.body?.components?.map((c) => c.calls))} updates=${JSON.stringify(req.body?.components?.map((c) => c.updates))}`);
+            res.status(status).send(e instanceof Error ? e.message : 'Error');
+        }
+    });
+    // File uploads: URL signed by `_startUpload`, CSRF token in a header, files stored in the temporary directory.
+    router.post(`${prefix}/upload-file`, async (req, res) => {
+        try {
+            const store = runtime.uploads;
+            if (!store)
+                throw new WireError(404, 'Uploads are not available.');
+            if (!store.verifySignature(req.query.expires, req.query.signature))
+                throw new WireError(401, 'Invalid or expired upload URL.');
+            if (!verifyCsrf(req, req.get('x-csrf-token')))
+                throw new WireError(419, 'Invalid CSRF token.');
+            if (!(await canUpload(await makeContext(req, res))))
+                throw new WireError(401, 'Unauthenticated.');
+            res.json({ paths: await store.receive(req) });
+        }
+        catch (e) {
+            const status = e instanceof WireError ? e.status : Number(e?.status) || 500;
+            if (status === 500)
+                console.error(e);
+            res.status(status).json({ message: e instanceof Error ? e.message : 'Error' });
+        }
+    });
+    return router;
+}
+/** `<script>` tag that loads livewire.js with its CSRF token and endpoint URLs. */
+export function wireScripts(req, res, prefix = '/livewire') {
+    return `<script src="${prefix}/livewire.js?id=${versionHash}" data-csrf="${csrfToken(req, res)}" data-module-url="${prefix}" data-update-uri="${prefix}/update" data-navigate-once="true"></script>`;
+}
+/** Styles livewire.js expects (loading states, cloak, progress bar); place them in `<head>`. */
+export function wireStyles(progressBarColor = '#2299dd') {
+    const BS = String.fromCharCode(92); // backslash: escapes `:` and `.` in CSS selectors
+    const sel = (n) => `[wire${BS}:${n.replaceAll('.', BS + '.')}]`;
+    const doubled = (names) => names.map((n) => sel(n) + sel(n)).join(', ');
+    return '<!-- Livewire Styles --><style>'
+        + doubled(['loading', 'loading.delay', 'loading.list-item', 'loading.inline-block', 'loading.inline', 'loading.block', 'loading.flex', 'loading.table', 'loading.grid', 'loading.inline-flex']) + ' {display: none;}'
+        + doubled(['loading.delay.none', 'loading.delay.shortest', 'loading.delay.shorter', 'loading.delay.short', 'loading.delay.default', 'loading.delay.long', 'loading.delay.longer', 'loading.delay.longest']) + ' {display: none;}'
+        + doubled(['offline']) + ' {display: none;}'
+        + sel('dirty') + ':not(textarea):not(input):not(select) {display: none;}'
+        + `:root {--livewire-progress-bar-color: ${progressBarColor};}`
+        + '[x-cloak="x-cloak"],[x-cloak=""] {display: none !important;}'
+        + sel('cloak').replace(']', '="wire:cloak"]') + ',' + sel('cloak').replace(']', '=""]') + ' {display: none !important;}'
+        + 'dialog#livewire-error::backdrop {background-color: rgba(0, 0, 0, .6);}</style>';
+}

package/lib/index.d.ts

@@ -0,0 +1,154 @@
+import { UploadStore } from './uploads.ts';
+export { UploadStore, type TemporaryFile } from './uploads.ts';
+export type Effects = {
+    html?: string;
+    returns?: unknown[];
+    dispatches?: {
+        name: string;
+        params: Record<string, unknown>;
+        self?: boolean;
+        to?: string;
+    }[];
+    redirect?: string;
+    redirectUsingNavigate?: boolean;
+    partials?: Record<string, string>;
+    [key: string]: unknown;
+};
+export type Snapshot = {
+    data: Record<string, unknown>;
+    memo: Record<string, any>;
+    checksum: string;
+};
+export type Call = {
+    method: string;
+    params: unknown[];
+    metadata?: Record<string, unknown>;
+};
+type ComponentClass = (new () => Component) & {
+    componentName?: string;
+    callable?: string[];
+    locked?: string[];
+    reactive?: string[];
+    listeners?: Record<string, string>;
+};
+export declare class WireError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/** Base class of a component. Every own enumerable property not starting with `_` is public state. */
+export declare abstract class Component {
+    _id: string;
+    _effects: Effects;
+    _skipRender: boolean;
+    _errors: Record<string, string[]>;
+    /** Context of the current HTTP request (request, response, panel…), supplied by the integration. */
+    _ctx: any;
+    /** Runtime and originating request, used to mount child components while rendering. */
+    _runtime: WireRuntime | null;
+    _request: {
+        path?: string;
+        method?: string;
+    };
+    /** Children rendered during this request, and children already in the browser: key → [tag, id]. */
+    _children: Record<string, [string, string]>;
+    _previousChildren: Record<string, [string, string]>;
+    /** HTML shown until a lazy component is loaded; must have a single root. */
+    placeholder(): string | Promise<string>;
+    /**
+     * Mounts a child component and returns its HTML, to insert into the parent's render.
+     * If the browser already has this child (same key), only a stub is rendered and the client keeps the child as is.
+     * `lazy`: the child shows its `placeholder()` and loads once it becomes visible.
+     */
+    mountChild(name: string, params: Record<string, unknown>, key: string, options?: {
+        lazy?: boolean;
+    }): Promise<string>;
+    /** Renders the component's HTML; must have a single root element. */
+    abstract render(): string | Promise<string>;
+    mount(_params: Record<string, unknown>): void | Promise<void>;
+    boot(): void | Promise<void>;
+    hydrate(): void | Promise<void>;
+    dehydrate(): void | Promise<void>;
+    get id(): string;
+    /** Dispatches a browser event; with `self`, only this component receives it. */
+    dispatch(name: string, params?: Record<string, unknown> | unknown[], options?: {
+        self?: boolean;
+    }): void;
+    redirect(url: string, navigate?: boolean): void;
+    skipRender(): void;
+    /** Partial render: only the `wire:partial="<name>"` fragment is sent back (effects.partials), the component is not re-rendered. */
+    renderPartial(name: string, html: string): void;
+    addError(path: string, message: string): void;
+    resetErrorBag(): void;
+}
+/**
+ * Methods callable from the browser: only those the class (or a parent class) lists in `static callable`.
+ * TypeScript erases `protected` and `private` at runtime: without this allowlist, any internal method could be called by a
+ * forged request and its return value sent back to the browser.
+ */
+export declare function callableMethods(component: Component): Set<string>;
+export declare function publicProperties(component: Component): string[];
+export declare function dehydrateValue(value: unknown): unknown;
+export declare function hydrateValue(value: unknown): unknown;
+/** Adds attributes to the root element of an HTML fragment. */
+export declare function insertAttributesIntoHtmlRoot(html: string, attributes: Record<string, unknown>): string;
+export type RuntimeOptions = {
+    key: string;
+    locale?: string; /** Temporary upload store; without it, file uploads are refused. */
+    uploads?: UploadStore;
+    uploadPrefix?: string;
+};
+export declare class WireRuntime {
+    private registry;
+    private options;
+    constructor(options: RuntimeOptions);
+    get uploads(): UploadStore | null;
+    /** Params passed by a parent to its existing children during the current request: child id → params. */
+    private requestScope;
+    passPropsToChild(childId: string, params: Record<string, unknown>): void;
+    private names;
+    register(name: string, cls: ComponentClass): this;
+    /** Name under which this runtime registered a class. A class shared by several runtimes (one per panel) keeps one name per runtime. */
+    nameOf(cls: ComponentClass): string;
+    private make;
+    checksum(snapshot: Omit<Snapshot, 'checksum'>): string;
+    private snapshot;
+    /** Signed mount params of a lazy component, in a `__mountParamsContainer`: the browser sends them back unchanged to `__lazyLoad`. */
+    private encodeMountParams;
+    private decodeMountParams;
+    /** A mount param named like a public property is copied into it. */
+    private assignMatchingProperties;
+    private renderRoot;
+    /**
+     * Initial render: HTML with wire:snapshot and wire:effects on the root.
+     * The memo only carries `lazyLoaded` / `lazyIsolated` for lazy components: their mere presence makes the client ignore events.
+     */
+    mount(name: string, params?: Record<string, unknown>, request?: {
+        path?: string;
+        method?: string;
+        ctx?: unknown;
+    }): Promise<string>;
+    /** Like mount(), but also returns the mounted instance (to read its title, for example). */
+    mountWithInstance(name: string, params?: Record<string, unknown>, request?: {
+        path?: string;
+        method?: string;
+        ctx?: unknown;
+        lazy?: boolean;
+        key?: string;
+    }): Promise<{
+        html: string;
+        component: Component;
+    }>;
+    /** Component update request: hydrate, apply updates, run calls, render, dehydrate. */
+    update(snapshot: Snapshot, updates: Record<string, unknown>, calls: Call[], ctx?: unknown): Promise<{
+        snapshot: Snapshot;
+        effects: Effects;
+    }>;
+    /** HTTP entry point; body: `{ _token, components: [{ snapshot, updates, calls }] }`. */
+    handle(body: any, ctx?: unknown): Promise<{
+        components: {
+            snapshot: string;
+            effects: Effects;
+        }[];
+        assets: unknown[];
+    }>;
+}