@sigmx/astro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Callum Bonnyman
+
+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

@@ -0,0 +1,26 @@
+# @sigmx/astro
+
+Astro integration and server helpers for [sigmx](../../README.md).
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import sigmx from '@sigmx/astro'
+
+export default defineConfig({ integrations: [sigmx()] })
+```
+
+```ts
+// src/pages/api/hello.ts
+import { readSignals, sseStream } from '@sigmx/astro/server'
+export const prerender = false
+export const GET = async ({ request }) => {
+  const { name } = await readSignals(request)
+  return sseStream(async (s) => {
+    s.patchSignals({ greeting: `hello ${name}` })
+    s.patchElements(`<p id="out">hello ${name}</p>`)
+  })
+}
+```
+
+Full guide: the sigmx documentation site in `website/` of https://github.com/wrux/sigmx, page "SDKs → Astro".

package/dist/client.d.ts

@@ -0,0 +1,4 @@
+export * from 'sigmx';
+export * as plugins from 'sigmx/plugins';
+export { all } from 'sigmx/presets/all';
+export { minimal } from 'sigmx/presets/minimal';

package/dist/client.js

@@ -0,0 +1,7 @@
+// Convenience re-exports for app-local entrypoints:
+//   import { createSigmx, all, plugins } from '@sigmx/astro/client'
+//   createSigmx({ plugins: [plugins.text, plugins.on] })
+export * from 'sigmx';
+export * as plugins from 'sigmx/plugins';
+export { all } from 'sigmx/presets/all';
+export { minimal } from 'sigmx/presets/minimal';

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import type { AstroIntegration } from 'astro';
+import { type AutoOptions, type PrecompileOptions as CorePrecompileOptions } from 'sigmx/vite';
+export interface PrecompileOptions extends Omit<CorePrecompileOptions, 'root' | 'prefixes'> {
+    /**
+     * Keep the runtime compiler as a fallback for expressions the scan cannot see (markup built from
+     * strings at render time). Default true. Set false to drop the compiler from the bundle entirely;
+     * unseen expressions then throw.
+     */
+    fallback?: boolean;
+}
+export interface SigmxIntegrationOptions {
+    /**
+     * Inject the client on every page (default true). Set false and import `@sigmx/astro/client`
+     * from a `<script>` on the pages that need it.
+     */
+    inject?: boolean;
+    /**
+     * Module specifier of an app-local entrypoint that creates the instance itself, e.g.
+     * `/src/sigmx.ts`. When set, the other client options are ignored.
+     */
+    entrypoint?: string;
+    /**
+     * `'all'` (default), `'minimal'`, `'auto'` (scan `src/` and register only what is used), or a
+     * list of plugin export names from `sigmx/plugins`.
+     */
+    plugins?: 'all' | 'minimal' | 'auto' | string[];
+    /** Options for `plugins: 'auto'`: `always`, `custom`, `include`, `extensions`, `log`. */
+    auto?: Omit<AutoOptions, 'root' | 'prefixes'>;
+    /** Attribute prefix(es) to scan. Default `data-`. */
+    prefix?: string | string[];
+    /** Server event-name prefixes to accept. Default `sigmx-`. */
+    eventPrefix?: string | string[];
+    /** Name of the global the instance is exposed as (default `sigmx`); false for none. */
+    expose?: string | false;
+    /**
+     * Compile attribute expressions at build time into a function table, so the browser never calls
+     * `new Function`. `true` for defaults, or an options object.
+     */
+    precompile?: boolean | PrecompileOptions;
+}
+/** Source of the injected client module. Exported for tests and custom entrypoints. */
+export declare const bootScript: (o?: SigmxIntegrationOptions) => string;
+export default function sigmx(options?: SigmxIntegrationOptions): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,41 @@
+import { sigmxAuto, sigmxPrecompile } from 'sigmx/vite';
+const AUTO = 'virtual:sigmx-plugins';
+const EXPRESSIONS = 'virtual:sigmx-expressions';
+/** Source of the injected client module. Exported for tests and custom entrypoints. */
+export const bootScript = (o = {}) => {
+    const options = JSON.stringify({ prefix: o.prefix, eventPrefix: o.eventPrefix });
+    const imports = Array.isArray(o.plugins)
+        ? `import { ${o.plugins.join(', ')} } from 'sigmx/plugins';\nconst plugins = [${o.plugins.join(', ')}];`
+        : o.plugins === 'auto'
+            ? `import { plugins } from '${AUTO}';`
+            : `import { ${o.plugins ?? 'all'} as plugins } from 'sigmx/presets/${o.plugins ?? 'all'}';`;
+    const expose = o.expose === false ? '' : `\nwindow[${JSON.stringify(o.expose ?? 'sigmx')}] = app;`;
+    if (!o.precompile)
+        return `import { createSigmx } from 'sigmx';\n${imports}\nconst app = createSigmx({ plugins, ...${options} });${expose}\n`;
+    const fallback = typeof o.precompile === 'object' && o.precompile.fallback === false ? 'undefined' : 'runtimeExpressions(functionCompiler)';
+    return (`import { createRuntime, precompiled, runtimeExpressions, functionCompiler } from 'sigmx';\nimport { table } from '${EXPRESSIONS}';\n${imports}\n` +
+        `const app = createRuntime({ plugins, expressions: precompiled(table, ${fallback}), ...${options} });${expose}\n`);
+};
+export default function sigmx(options = {}) {
+    return {
+        name: '@sigmx/astro',
+        hooks: {
+            'astro:config:setup': ({ injectScript, updateConfig, config }) => {
+                const root = new URL(config.root).pathname;
+                const prefixes = [].concat(options.prefix ?? 'data-');
+                const plugins = [];
+                if (options.plugins === 'auto')
+                    plugins.push(sigmxAuto({ ...options.auto, root, prefixes }));
+                if (options.precompile) {
+                    const po = typeof options.precompile === 'object' ? options.precompile : {};
+                    plugins.push(sigmxPrecompile({ include: po.include, extensions: po.extensions, custom: po.custom ?? options.auto?.custom, root, prefixes }));
+                }
+                if (plugins.length)
+                    updateConfig({ vite: { plugins } });
+                if (options.inject === false)
+                    return;
+                injectScript('page', options.entrypoint ? `import ${JSON.stringify(options.entrypoint)};` : bootScript(options));
+            },
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,106 @@
+/** Query-string key that carries signals on GET/DELETE requests. */
+export declare const SIGNALS_KEY = "sigmx";
+export declare const EVENT_PATCH_ELEMENTS = "sigmx-patch-elements";
+export declare const EVENT_PATCH_SIGNALS = "sigmx-patch-signals";
+export declare const SSE_HEADERS: {
+    readonly 'content-type': "text/event-stream";
+    readonly 'cache-control': "no-cache";
+    readonly connection: "keep-alive";
+};
+export type PatchMode = 'outer' | 'inner' | 'replace' | 'prepend' | 'append' | 'before' | 'after' | 'remove';
+export interface ServerEvent {
+    event: string;
+    /** Data lines, each `key value`. */
+    lines: string[];
+    id?: string;
+    retry?: number;
+}
+export interface EventOptions {
+    id?: string;
+    retry?: number;
+}
+export interface PatchElementsOptions extends EventOptions {
+    selector?: string;
+    mode?: PatchMode;
+    useViewTransition?: boolean;
+}
+export interface PatchSignalsOptions extends EventOptions {
+    onlyIfMissing?: boolean;
+}
+export interface ExecuteScriptOptions extends EventOptions {
+    /** Remove the script element after it runs (default true). */
+    autoRemove?: boolean;
+    attributes?: Record<string, string>;
+}
+/** Patch HTML into the page. Without a selector, top-level elements are morphed by id. */
+export declare const patchElements: (html: string, o?: PatchElementsOptions) => ServerEvent;
+export declare const removeElements: (selector: string, o?: EventOptions) => ServerEvent;
+/** Merge signals (JSON merge-patch: null removes). Accepts an object or pre-serialised JSON. */
+export declare const patchSignals: (signals: Record<string, unknown> | string, o?: PatchSignalsOptions) => ServerEvent;
+/** Remove signals by dotted path. */
+export declare const removeSignals: (paths: string[], o?: EventOptions) => ServerEvent;
+/** Run JavaScript in the page by appending a script element to the body. */
+export declare const executeScript: (script: string, o?: ExecuteScriptOptions) => ServerEvent;
+/** Serialise one event in `text/event-stream` format. */
+export declare const formatEvent: (e: ServerEvent) => string;
+/** A streaming event-source response you write to over time. */
+export declare class SigmxStream {
+    readonly response: Response;
+    private controller;
+    private readonly encoder;
+    private open;
+    constructor(init?: ResponseInit);
+    get closed(): boolean;
+    send(event: ServerEvent): this;
+    patchElements(html: string, o?: PatchElementsOptions): this;
+    removeElements(selector: string, o?: EventOptions): this;
+    patchSignals(signals: Record<string, unknown> | string, o?: PatchSignalsOptions): this;
+    removeSignals(paths: string[], o?: EventOptions): this;
+    executeScript(script: string, o?: ExecuteScriptOptions): this;
+    close(): void;
+}
+/** A complete event-source response from a fixed list of events. */
+export declare const sse: (...events: ServerEvent[]) => Response;
+/** Stream events while `fn` runs; the response closes when it resolves. */
+export declare const sseStream: (fn: (stream: SigmxStream) => Promise<void> | void, init?: ResponseInit) => Response;
+/** A plain HTML response; the client morphs it by id, or honours the selector and mode headers. */
+export declare const html: (body: string, o?: PatchElementsOptions & {
+    status?: number;
+}) => Response;
+/** A plain JSON response; the client merges it as signals. */
+export declare const json: (signals: Record<string, unknown>, o?: PatchSignalsOptions & {
+    status?: number;
+}) => Response;
+/** Minimal Standard Schema (standardschema.dev) so any compliant validator works without a dependency. */
+export interface StandardSchema<Output = unknown> {
+    readonly '~standard': {
+        readonly validate: (value: unknown) => SchemaResult<Output> | Promise<SchemaResult<Output>>;
+    };
+}
+export type SchemaIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+};
+export type SchemaResult<T> = {
+    readonly value: T;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<SchemaIssue>;
+};
+export declare class SignalsError extends Error {
+    readonly issues: ReadonlyArray<SchemaIssue>;
+    readonly status: number;
+    constructor(message: string, issues?: ReadonlyArray<SchemaIssue>, status?: number);
+    /** A ready-made error response for endpoints that want to bail out. */
+    response(): Response;
+}
+/**
+ * Read the signals a sigmx request carries: the `sigmx` query parameter on GET/DELETE, a JSON
+ * body otherwise, or form fields for `contentType: 'form'` requests. Validates with `schema` if given.
+ */
+export declare function readSignals(request: Request): Promise<Record<string, any>>;
+export declare function readSignals<T>(request: Request, schema: StandardSchema<T>): Promise<T>;
+/** True when the request was made by the sigmx client (has the `Sigmx-Request` header). */
+export declare const isSigmxRequest: (request: Request) => boolean;

package/dist/server.js

@@ -0,0 +1,181 @@
+// Server helpers for answering sigmx requests from Astro endpoints (or any Fetch-API runtime).
+/** Query-string key that carries signals on GET/DELETE requests. */
+export const SIGNALS_KEY = 'sigmx';
+export const EVENT_PATCH_ELEMENTS = 'sigmx-patch-elements';
+export const EVENT_PATCH_SIGNALS = 'sigmx-patch-signals';
+export const SSE_HEADERS = {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+};
+// ---- event builders -------------------------------------------------------
+/** Patch HTML into the page. Without a selector, top-level elements are morphed by id. */
+export const patchElements = (html, o = {}) => {
+    const lines = [];
+    if (o.selector)
+        lines.push(`selector ${o.selector}`);
+    if (o.mode && o.mode !== 'outer')
+        lines.push(`mode ${o.mode}`);
+    if (o.useViewTransition)
+        lines.push('useViewTransition true');
+    for (const l of html.trim().split('\n'))
+        lines.push(`elements ${l}`);
+    return { event: EVENT_PATCH_ELEMENTS, lines, id: o.id, retry: o.retry };
+};
+export const removeElements = (selector, o = {}) => ({
+    event: EVENT_PATCH_ELEMENTS,
+    lines: [`selector ${selector}`, 'mode remove'],
+    ...o,
+});
+/** Merge signals (JSON merge-patch: null removes). Accepts an object or pre-serialised JSON. */
+export const patchSignals = (signals, o = {}) => ({
+    event: EVENT_PATCH_SIGNALS,
+    lines: [...(o.onlyIfMissing ? ['onlyIfMissing true'] : []), `signals ${typeof signals === 'string' ? signals : JSON.stringify(signals)}`],
+    id: o.id,
+    retry: o.retry,
+});
+/** Remove signals by dotted path. */
+export const removeSignals = (paths, o = {}) => {
+    const patch = {};
+    for (const p of paths) {
+        const keys = p.split('.');
+        const last = keys.pop();
+        let cur = patch;
+        for (const k of keys)
+            cur = cur[k] ??= {};
+        cur[last] = null;
+    }
+    return patchSignals(patch, o);
+};
+/** Run JavaScript in the page by appending a script element to the body. */
+export const executeScript = (script, o = {}) => {
+    const attrs = { ...(o.autoRemove ?? true ? { 'data-init': 'el.remove()' } : {}), ...o.attributes };
+    const attrText = Object.entries(attrs)
+        .map(([k, v]) => ` ${k}="${v.replace(/"/g, '"')}"`)
+        .join('');
+    return patchElements(`<script${attrText}>${script}</script>`, { selector: 'body', mode: 'append', id: o.id, retry: o.retry });
+};
+/** Serialise one event in `text/event-stream` format. */
+export const formatEvent = (e) => [e.id !== undefined && `id: ${e.id}`, e.retry !== undefined && `retry: ${e.retry}`, `event: ${e.event}`, ...e.lines.map((l) => `data: ${l}`)]
+    .filter(Boolean)
+    .join('\n') + '\n\n';
+// ---- responses ------------------------------------------------------------
+/** A streaming event-source response you write to over time. */
+export class SigmxStream {
+    response;
+    controller;
+    encoder = new TextEncoder();
+    open = true;
+    constructor(init = {}) {
+        const body = new ReadableStream({
+            start: (c) => {
+                this.controller = c;
+            },
+            cancel: () => {
+                this.open = false;
+            },
+        });
+        this.response = new Response(body, { ...init, headers: { ...SSE_HEADERS, ...init.headers } });
+    }
+    get closed() {
+        return !this.open;
+    }
+    send(event) {
+        if (this.open)
+            this.controller.enqueue(this.encoder.encode(formatEvent(event)));
+        return this;
+    }
+    patchElements(html, o) {
+        return this.send(patchElements(html, o));
+    }
+    removeElements(selector, o) {
+        return this.send(removeElements(selector, o));
+    }
+    patchSignals(signals, o) {
+        return this.send(patchSignals(signals, o));
+    }
+    removeSignals(paths, o) {
+        return this.send(removeSignals(paths, o));
+    }
+    executeScript(script, o) {
+        return this.send(executeScript(script, o));
+    }
+    close() {
+        if (this.open) {
+            this.open = false;
+            this.controller.close();
+        }
+    }
+}
+/** A complete event-source response from a fixed list of events. */
+export const sse = (...events) => new Response(events.map(formatEvent).join(''), { headers: SSE_HEADERS });
+/** Stream events while `fn` runs; the response closes when it resolves. */
+export const sseStream = (fn, init) => {
+    const stream = new SigmxStream(init);
+    Promise.resolve()
+        .then(() => fn(stream))
+        .catch((e) => console.error('sigmx sseStream:', e))
+        .finally(() => stream.close());
+    return stream.response;
+};
+/** A plain HTML response; the client morphs it by id, or honours the selector and mode headers. */
+export const html = (body, o = {}) => new Response(body, {
+    status: o.status ?? 200,
+    headers: {
+        'content-type': 'text/html; charset=utf-8',
+        ...(o.selector ? { 'sigmx-selector': o.selector } : {}),
+        ...(o.mode ? { 'sigmx-mode': o.mode } : {}),
+        ...(o.useViewTransition ? { 'sigmx-use-view-transition': 'true' } : {}),
+    },
+});
+/** A plain JSON response; the client merges it as signals. */
+export const json = (signals, o = {}) => new Response(JSON.stringify(signals), {
+    status: o.status ?? 200,
+    headers: { 'content-type': 'application/json', ...(o.onlyIfMissing ? { 'sigmx-only-if-missing': 'true' } : {}) },
+});
+export class SignalsError extends Error {
+    issues;
+    status;
+    constructor(message, issues = [], status = 422) {
+        super(message);
+        this.issues = issues;
+        this.status = status;
+        this.name = 'SignalsError';
+    }
+    /** A ready-made error response for endpoints that want to bail out. */
+    response() {
+        return Response.json({ error: this.message, issues: this.issues }, { status: this.status });
+    }
+}
+export async function readSignals(request, schema) {
+    let raw;
+    const method = request.method.toUpperCase();
+    const type = request.headers.get('content-type') ?? '';
+    try {
+        if (method === 'GET' || method === 'DELETE') {
+            const q = new URL(request.url).searchParams.get(SIGNALS_KEY);
+            raw = q ? JSON.parse(q) : {};
+        }
+        else if (type.includes('application/json')) {
+            const text = await request.text();
+            raw = text ? JSON.parse(text) : {};
+        }
+        else if (type.includes('form')) {
+            raw = Object.fromEntries((await request.formData()).entries());
+        }
+        else {
+            raw = {};
+        }
+    }
+    catch (e) {
+        throw new SignalsError(`could not parse signals: ${e.message}`, [], 400);
+    }
+    if (!schema)
+        return raw;
+    const result = await schema['~standard'].validate(raw);
+    if (result.issues)
+        throw new SignalsError(`invalid signals: ${result.issues.map((i) => i.message).join('; ')}`, result.issues);
+    return result.value;
+}
+/** True when the request was made by the sigmx client (has the `Sigmx-Request` header). */
+export const isSigmxRequest = (request) => request.headers.get('sigmx-request') === 'true';

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@sigmx/astro",
+  "version": "0.1.0",
+  "description": "Astro integration and server helpers for sigmx: inject the client, stream patches from endpoints, read signals from requests.",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "sigmx",
+    "hypermedia",
+    "sse"
+  ],
+  "author": "Callum Bonnyman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wrux/sigmx.git",
+    "directory": "sdks/astro"
+  },
+  "homepage": "https://github.com/wrux/sigmx#readme",
+  "bugs": {
+    "url": "https://github.com/wrux/sigmx/issues"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepublishOnly": "npm test",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "astro": "^7.3.1",
+    "sigmx": "file:../..",
+    "typescript": "^5.9.0"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0 || ^6.0.0 || ^7.0.0",
+    "sigmx": "^0.1.0"
+  }
+}