@tyndall/wasm 0.0.1

package/README.md

@@ -0,0 +1,27 @@
+# @tyndall/wasm
+
+## Overview
+WebAssembly adapter package implementing UIAdapter contracts for WASM-backed rendering pipelines.
+
+## Responsibilities
+- Provide WASM adapter, factory, and registry implementations
+- Provide WASM instantiation helper for runtime setup
+
+## Public API Highlights
+- createWasmAdapter
+- instantiateWasmModule
+- createWasmAdapterRegistry
+
+## Development
+- Build: bun run --filter @tyndall/wasm build
+- Test (from workspace root): bun test
+
+## Documentation
+- Package specification: [spec.md](./spec.md)
+- Package architecture: [architecture.md](./architecture.md)
+- Package changes: [CHANGELOG.md](./CHANGELOG.md)
+
+## Maintenance Rules
+- Keep this document aligned with implemented package behavior.
+- Update spec.md and architecture.md whenever package contracts or design boundaries change.
+- Record user-visible package changes in CHANGELOG.md.

package/dist/adapter.d.ts

@@ -0,0 +1,16 @@
+import type { HeadDescriptor, HmrIntegration, UIAdapter, UIAdapterEntryContext, UIAdapterRenderContext, UIAdapterRenderResult } from "@tyndall/core";
+export interface WasmAdapterRenderContext extends UIAdapterRenderContext {
+    instance: WebAssembly.Instance | null;
+}
+export interface WasmAdapterOptions {
+    name?: string;
+    createClientEntry?: (ctx: UIAdapterEntryContext) => string;
+    createServerEntry?: (ctx: UIAdapterEntryContext) => string;
+    renderToHtml?: (ctx: UIAdapterRenderContext) => Promise<UIAdapterRenderResult> | UIAdapterRenderResult;
+    instantiate?: (ctx: UIAdapterRenderContext) => Promise<WebAssembly.Instance | null> | WebAssembly.Instance | null;
+    render?: (ctx: WasmAdapterRenderContext) => Promise<unknown> | unknown;
+    getHead?: (ctx: UIAdapterRenderContext) => HeadDescriptor;
+    hmrIntegration?: HmrIntegration;
+}
+export declare const createWasmAdapter: (options?: WasmAdapterOptions) => UIAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,SAAS,EACT,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACtE,QAAQ,EAAE,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,MAAM,CAAC;IAC3D,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,MAAM,CAAC;IAC3D,YAAY,CAAC,EAAE,CACb,GAAG,EAAE,sBAAsB,KACxB,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAAC;IAC5D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,sBAAsB,KACxB,OAAO,CAAC,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC;IACxE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,wBAAwB,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACvE,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,cAAc,CAAC;IAC1D,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AA4ED,eAAO,MAAM,iBAAiB,GAAI,UAAS,kBAAuB,KAAG,SAQnE,CAAC"}

package/dist/adapter.js

@@ -0,0 +1,72 @@
+import { mergeHeadDescriptors, serializeProps } from "@tyndall/core";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const resolvePageImport = (ctx) => {
+    const options = ctx.uiOptions ?? ctx.adapterOptions;
+    const pageModule = options?.pageModule;
+    const specifier = typeof pageModule === "string" ? pageModule : "./page";
+    return JSON.stringify(specifier);
+};
+const normalizeRenderResult = (value) => {
+    if (typeof value === "string") {
+        return { html: value };
+    }
+    if (isRecord(value) && typeof value.html === "string") {
+        return {
+            html: value.html,
+            head: isRecord(value.head) ? value.head : undefined,
+            status: typeof value.status === "number" ? value.status : undefined,
+            headers: isRecord(value.headers)
+                ? Object.fromEntries(Object.entries(value.headers).map(([key, header]) => [key, String(header)]))
+                : undefined,
+        };
+    }
+    return { html: String(value ?? "") };
+};
+const defaultClientEntry = (ctx) => {
+    const pageImport = resolvePageImport(ctx);
+    return [
+        `import Page from ${pageImport};`,
+        "if (Page && typeof Page.bootstrap === \"function\") {",
+        "  void Page.bootstrap();",
+        "}",
+    ].join("\n");
+};
+const defaultServerEntry = (ctx) => {
+    const pageImport = resolvePageImport(ctx);
+    return [
+        `import Page from ${pageImport};`,
+        "export const renderToHtml = async (ctx) => {",
+        "  if (Page && typeof Page.render === \"function\") {",
+        "    const html = await Page.render(ctx.props ?? {});",
+        "    return { html: typeof html === \"string\" ? html : String(html ?? \"\") };",
+        "  }",
+        "  return { html: `<div data-hyper-wasm=\\\"true\\\">${ctx.routeId}</div>` };",
+        "};",
+    ].join("\n");
+};
+const defaultRenderToHtml = async (ctx, options) => {
+    const instance = options.instantiate ? await options.instantiate(ctx) : null;
+    if (!options.render) {
+        return {
+            html: `<div data-hyper-wasm=\"true\" data-hyper-wasm-ready=\"${instance ? "true" : "false"}\">${ctx.routeId}</div>`,
+        };
+    }
+    const rendered = await options.render({ ...ctx, instance });
+    const normalized = normalizeRenderResult(rendered);
+    const providedHead = options.getHead?.(ctx);
+    // Keep adapter-provided head as the final override for deterministic composition.
+    const head = mergeHeadDescriptors(normalized.head ?? {}, providedHead ?? {});
+    return {
+        ...normalized,
+        head,
+    };
+};
+export const createWasmAdapter = (options = {}) => ({
+    name: options.name ?? "wasm",
+    createClientEntry: options.createClientEntry ?? defaultClientEntry,
+    createServerEntry: options.createServerEntry ?? defaultServerEntry,
+    renderToHtml: options.renderToHtml ?? ((ctx) => defaultRenderToHtml(ctx, options)),
+    serializeProps,
+    getHead: options.getHead,
+    hmrIntegration: options.hmrIntegration,
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createWasmAdapter } from "./adapter.js";
+export type { WasmAdapterOptions, WasmAdapterRenderContext } from "./adapter.js";
+export { createWasmAdapterRegistry, createWasmUiAdapterFactory } from "./registry.js";
+export { instantiateWasmModule } from "./wasm.js";
+export type { WasmBinarySource } from "./wasm.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createWasmAdapter } from "./adapter.js";
+export { createWasmAdapterRegistry, createWasmUiAdapterFactory } from "./registry.js";
+export { instantiateWasmModule } from "./wasm.js";

package/dist/registry.d.ts

@@ -0,0 +1,4 @@
+import type { UIAdapterFactory, UIAdapterRegistry } from "@tyndall/core";
+export declare const createWasmUiAdapterFactory: () => UIAdapterFactory;
+export declare const createWasmAdapterRegistry: () => UIAdapterRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAWzF,eAAO,MAAM,0BAA0B,QAAO,gBAiB7C,CAAC;AAEF,eAAO,MAAM,yBAAyB,QAAO,iBAE3C,CAAC"}

package/dist/registry.js

@@ -0,0 +1,18 @@
+import { createWasmAdapter } from "./adapter.js";
+const isFunction = (value) => typeof value === "function";
+export const createWasmUiAdapterFactory = () => (options) => {
+    const normalized = options;
+    const routeRender = isFunction(normalized.routeRender)
+        ? normalized.routeRender
+        : undefined;
+    const routeHead = isFunction(normalized.routeHead)
+        ? normalized.routeHead
+        : undefined;
+    return createWasmAdapter({
+        render: routeRender ? ({ props }) => routeRender(props) : undefined,
+        getHead: routeHead ? ({ props }) => routeHead(props) : undefined,
+    });
+};
+export const createWasmAdapterRegistry = () => ({
+    wasm: createWasmUiAdapterFactory(),
+});

package/dist/wasm.d.ts

@@ -0,0 +1,3 @@
+export type WasmBinarySource = ArrayBuffer | Uint8Array;
+export declare const instantiateWasmModule: (source: WasmBinarySource, imports?: WebAssembly.Imports) => Promise<WebAssembly.Instance>;
+//# sourceMappingURL=wasm.d.ts.map

package/dist/wasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.d.ts","sourceRoot":"","sources":["../src/wasm.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,CAAC;AAExD,eAAO,MAAM,qBAAqB,GAChC,QAAQ,gBAAgB,EACxB,UAAS,WAAW,CAAC,OAAY,KAChC,OAAO,CAAC,WAAW,CAAC,QAAQ,CAU9B,CAAC"}

package/dist/wasm.js

@@ -0,0 +1,8 @@
+export const instantiateWasmModule = async (source, imports = {}) => {
+    const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
+    const instantiated = (await WebAssembly.instantiate(bytes, imports));
+    if ("instance" in instantiated) {
+        return instantiated.instance;
+    }
+    return instantiated;
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tyndall/wasm",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tyndall/core": "workspace:*",
+    "@tyndall/shared": "workspace:*"
+  }
+}