@live-codes/pascal-wasm 0.1.0

package/README.md

@@ -0,0 +1,278 @@
+# @live-codes/pascal-wasm
+
+The [pas2js](https://www.freepascal.org/) compiler — the Free Pascal team's
+Pascal → JavaScript transpiler — compiled to WebAssembly, for use in browsers and
+Web Workers.
+
+Compilation runs entirely on the client. There is no server, no account, and the
+source never leaves the page.
+
+```js
+import { compile } from '@live-codes/pascal-wasm';
+
+const { js, diagnostics } = await compile(`
+  program hello;
+  begin
+    Writeln('Hello from Pascal');
+  end.
+`);
+
+if (js) {
+  // `js` defines the program and the pas2js runtime; the host starts it.
+  document.body.append(Object.assign(document.createElement('script'), { textContent: js }));
+  rtl.run();
+}
+```
+
+## Install
+
+```sh
+npm install @live-codes/pascal-wasm
+```
+
+Or import it straight from a CDN — the package resolves its own assets relative
+to itself, so no configuration is needed:
+
+```js
+import { compile } from 'https://cdn.jsdelivr.net/npm/@live-codes/pascal-wasm@0.1.0/src/index.js';
+```
+
+There is also a minified **classic-script build** for non-module workers and
+plain `<script>` tags, at `dist/pascal-wasm.iife.min.js` — see
+[Classic scripts and non-module workers](#classic-scripts-and-non-module-workers).
+Both builds share the same `assets/`.
+
+## API
+
+### `compile(source, options?)`
+
+One-shot convenience call. Reuses a shared compiler instance.
+
+Returns `Promise<CompileResult>`:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `js` | `string \| null` | The generated JavaScript, or `null` if compilation failed |
+| `sourceMap` | `string \| null` | The map, if `sourceMap: true` was requested |
+| `diagnostics` | `string` | Raw compiler output, including progress lines |
+| `exitCode` | `number` | `0` on success |
+
+Compilation *errors are not exceptions*: they come back as `js: null` with the
+details in `diagnostics`. Only failures to load the compiler itself reject.
+
+### `createCompiler(options?)`
+
+Returns `Promise<Compiler>` for reuse, which avoids re-loading the ~9 MB binary:
+
+```js
+const compiler = await createCompiler();
+await compiler.version();          // "3.3.1"
+await compiler.compile(source);
+```
+
+### `parseDiagnostics(diagnostics)`
+
+Turns the compiler's text output into structured messages, with the progress
+chatter filtered out. Useful for editor markers.
+
+```js
+parseDiagnostics(result.diagnostics);
+// [{ file: 'tmp/main.pp', line: 5, column: 11, severity: 'error',
+//    message: 'identifier not found "missingThing"' }]
+```
+
+`severity` is one of `error`, `warning`, `hint`, `note` or `fatal`.
+
+### `configure(options)`
+
+Sets package-wide defaults: `baseUrl` and `flags`. Per-call options win over
+these, and `flags` are prepended to each call's own `flags`.
+
+```js
+configure({ baseUrl: 'https://example.com/pascal/assets/', flags: ['-O2'] });
+```
+
+This is mainly for the classic-script build, where there is no import to attach
+options to.
+
+### `defaultBaseUrl()`
+
+Returns the asset location that will be used when none is given explicitly —
+useful for checking what was resolved.
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `flags` | `string[]` | Extra pas2js command-line options, appended as-is |
+| `units` | `Record<string, string \| Uint8Array>` or `Map` | Extra units by filename, placed on the compiler's search path |
+| `sourceMap` | `boolean` | Emit `js.map`, mapping generated JavaScript back to the Pascal |
+| `baseUrl` | `string \| URL` | Load `pas2js.wasm` and `rtl/` from somewhere else. Required by the IIFE build |
+| `wasmUrl` / `rtlUrl` | `string \| URL` | Override just one of the two |
+
+### Compiler options
+
+`flags` is a pass-through to the compiler, so anything pas2js accepts works. The
+ones you are most likely to want:
+
+| Flag | Effect |
+| --- | --- |
+| `-O2` | Optimization level |
+| `-dNAME` | Define a symbol for `{$IFDEF NAME}` |
+| `-Mobjfpc`, `-Mdelphi`, `-Mtp`, `-Miso` | Pascal dialect (modeswitch) |
+| `-C-`, `-Cr`, `-Co` | Range/overflow/object checking |
+| `-Jm` | Source maps, beyond what `sourceMap: true` sets up |
+
+The compiler can list what it supports. Pass a query switch and read the answer
+back from `diagnostics` — this is how the demo UI reports them:
+
+```js
+const { diagnostics } = await compiler.compile('', { flags: ['-iM'] }); // modeswitches
+// also: -it targets, -ic JS processors, -io optimizations
+```
+
+### Extra units
+
+Additional units are written into the compiler's unit search path:
+
+```js
+const result = await compile(
+  `program main; uses doubler; begin Writeln(Twice(21)); end.`,
+  {
+    units: {
+      'doubler.pas': `unit doubler;
+        interface
+        function Twice(x: Integer): Integer;
+        implementation
+        function Twice(x: Integer): Integer;
+        begin Twice := x * 2; end;
+        end.`,
+    },
+  },
+);
+```
+
+## Web Workers
+
+The package has no DOM dependencies, so it runs unchanged in a module worker —
+which is the sensible place for it, since compiling blocks for a moment.
+
+```js
+// compiler-worker.js
+import { createCompiler } from 'https://cdn.jsdelivr.net/npm/@live-codes/pascal-wasm@0.1.0/src/index.js';
+
+const compiler = await createCompiler();
+self.postMessage({ type: 'ready' });
+
+self.onmessage = async ({ data }) => {
+  self.postMessage({ type: 'result', ...(await compiler.compile(data.source)) });
+};
+```
+
+```js
+const worker = new Worker('compiler-worker.js', { type: 'module' });
+worker.onmessage = ({ data }) => {
+  if (data.type !== 'result' || !data.js) return;
+  const script = document.createElement('script');
+  script.textContent = data.js;
+  document.body.append(script);
+  rtl.run();
+};
+```
+
+Note the worker must be a *module* worker (`{ type: 'module' }`) because the
+package is ESM.
+
+## Classic scripts and non-module workers
+
+Not every consumer can use ES modules — a classic worker cannot, because
+`importScripts()` only runs classic scripts. For those, a minified IIFE bundle is
+shipped in `dist/`, exposing the same API on a global named `pascalWasm`:
+
+```js
+// compiler-worker.js — a *classic* worker, no { type: 'module' }
+importScripts('https://cdn.jsdelivr.net/npm/@live-codes/pascal-wasm@0.1.0/dist/pascal-wasm.iife.min.js');
+
+// This build has no module URL, so it cannot find the assets by itself.
+pascalWasm.configure({ baseUrl: 'https://cdn.jsdelivr.net/npm/@live-codes/pascal-wasm@0.1.0/assets/' });
+
+pascalWasm.compile('begin Writeln(42) end.').then(({ js, diagnostics }) => {
+  self.postMessage({ js, diagnostics });
+});
+```
+
+```js
+new Worker('compiler-worker.js'); // ...and no module type here either
+```
+
+```html
+<!-- the same bundle works as a plain script tag -->
+<script src="https://cdn.jsdelivr.net/npm/@live-codes/pascal-wasm@0.1.0/dist/pascal-wasm.iife.min.js"></script>
+<script>
+  pascalWasm.configure({ baseUrl: 'https://cdn.jsdelivr.net/npm/@live-codes/pascal-wasm@0.1.0/assets/' });
+  pascalWasm.compile('begin Writeln(42) end.').then(console.log);
+</script>
+```
+
+The bundle is ~27 kB and contains only the glue — the compiler itself stays in
+`assets/`, which is shared with the ES module build and cached between them.
+
+`baseUrl` can be relative, in which case it resolves against the worker's or page's
+own location:
+
+```js
+pascalWasm.configure({ baseUrl: '../packages/pascal-wasm/assets/' });
+```
+
+It may also be passed per call instead — `createCompiler({ baseUrl })` — which
+takes precedence over `configure()`. Calling `compile()` without a usable
+`baseUrl` in this build fails with an explanatory error rather than guessing,
+and `pascalWasm.defaultBaseUrl()` reports what a resolution would produce.
+
+## Running the compiled output
+
+pas2js emits a script that registers the program with its runtime but does not
+start it. The host document starts it with `rtl.run()`, and the program then
+behaves like any other page script: it can read and write the DOM (`uses web`),
+call host functions, and set `ExitCode`.
+
+Uncaught Pascal exceptions can be captured through the runtime's hooks:
+
+```js
+rtl.showUncaughtExceptions = true;
+rtl.onUncaughtException = (error) => {
+  console.error(error.$classname, error.fMessage);
+  return true; // handled — suppress the default alert()
+};
+rtl.run();
+```
+
+## Node
+
+The same API works in Node, reading the assets from disk. Node needs a flag for
+the WebAssembly exception-handling instructions this compiler uses:
+
+```sh
+node --experimental-wasm-exnref app.mjs
+```
+
+## Assets
+
+`assets/pas2js.wasm` is about 9 MB and `assets/rtl/` about 1.2 MB. The binary is
+downloaded and compiled once per compiler instance, then reused across calls.
+`compile()` memoizes instances by asset location.
+
+To host the assets yourself, either point `baseUrl` at your own copy, or import
+them from the package — `@live-codes/pascal-wasm/assets/...` is exported for that.
+
+## Licensing
+
+The package is licensed under **LGPL-2.1-or-later**, matching pas2js, which is
+itself LGPL-2.1 — this package redistributes its compiler binary and runtime
+library. The WASI shim it bundles is MIT OR Apache-2.0.
+
+See [`THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md) for versions, the
+provenance and SHA-256 of the compiler binary, and pointers to the corresponding
+source. Note in particular that the bundled binary comes from the official Free
+Pascal demo deployment rather than a tagged release, and that building it from
+source is preferable if you need a version-pinned artifact.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party notices
+
+This package redistributes third-party software. Their licenses are reproduced or
+referenced here; the package's own code is licensed under LGPL-2.1-or-later (see
+`LICENSE`).
+
+## pas2js compiler — `assets/pas2js.wasm`
+
+- **Project**: pas2js, the Pascal to JavaScript transpiler, part of Free Pascal
+  (<https://www.freepascal.org/>, source at
+  <https://gitlab.com/freepascal.org/fpc/pas2js>).
+- **License**: GNU Lesser General Public License v2.1 (LGPL-2.1).
+- **Binary**: the pas2js command-line compiler built for the `wasm32-wasi` target.
+- **Version**: `Pas2JS Compiler version 3.3.1 [2026/02/22] for Wasip1 wasm32`
+  (as reported by the binary).
+- **Source of the binary**: the deployment of the official Free Pascal browser
+  compiler demo, <https://live.freepascal.org/wasm/pas2js.wasm>.
+- **SHA-256**:
+  `ade2bc6334f971ce835ce8e2a1861c808de230e285767115021df38391841377`
+
+Note that this binary is **not** from a tagged pas2js release: the official
+release archives (currently 3.2.0) are per-platform native builds and contain no
+WebAssembly at all. It was taken from the official demo deployment above, which
+tracks pas2js trunk and is therefore newer than the latest release. Prefer
+building the compiler yourself from the pas2js sources (FPC plus `demo/webcompiler`
+in that tree, targeting wasm32-wasi) if you need a reproducible, version-pinned
+binary.
+
+### Corresponding source
+
+LGPL-2.1 requires that the corresponding source be available. It is the pas2js
+source tree linked above. To rebuild this binary, build the Free Pascal compiler
+with a `wasm32-wasi` target and compile pas2js with it.
+
+## Pascal RTL — `assets/rtl/`
+
+- **Project**: the pas2js runtime library, from the same source tree.
+- **License**: LGPL-2.1, with the Free Pascal static-linking exception that
+  applies to the runtime library.
+- **Source of these files**: <https://live.freepascal.org/files/> (the unit
+  manifest and sources the official browser compiler demo ships).
+
+## `@bjorn3/browser_wasi_shim` — `src/vendor/browser_wasi_shim/`
+
+- **Project**: <https://github.com/bjorn3/browser_wasi_shim>
+- **License**: MIT OR Apache-2.0 (dual licensed; either may be chosen).
+- **Version**: 0.4.2, vendored here so the package works from a CDN with no
+  additional resolver or dependency graph.

package/assets/rtl/Rtl.BrowserLoadHelper.pas

@@ -0,0 +1,179 @@
+{
+    This file is part of the Pas2JS run time library.
+    Copyright (c) 2023 by Michael Van Canneyt
+    
+    Loader helper for TStringList, usable in the browser.
+
+    See the file COPYING.FPC, included in this distribution,
+    for details about the copyright.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+ **********************************************************************}
+{$IFNDEF FPC_DOTTEDUNITS}
+unit Rtl.BrowserLoadHelper;
+{$ENDIF}
+
+{$mode objfpc}
+
+interface
+
+uses
+{$IFDEF FPC_DOTTEDUNITS}
+  System.Classes, System.SysUtils, JSApi.JS, BrowserApi.Web;
+{$ELSE}
+  Classes, SysUtils, JS, Web;
+{$ENDIF}  
+
+Type
+  { TBrowserLoadHelper }
+
+  TBrowserLoadHelper = Class (TLoadHelper)
+  Public
+    Class Procedure LoadText(aURL : String; aSync : Boolean; aOnLoaded : TTextLoadedCallBack; aOnError : TErrorCallBack); override;
+    Class Procedure LoadBytes(aURL : String; aSync : Boolean; aOnLoaded : TBytesLoadedCallBack; aOnError : TErrorCallBack); override;
+  end;
+
+implementation
+
+{ TBrowserLoadHelper }
+
+class procedure TBrowserLoadHelper.LoadText(aURL: String; aSync: Boolean; aOnLoaded: TTextLoadedCallBack; aOnError: TErrorCallBack);
+
+  function doFetchOK(response : JSValue) : JSValue;
+
+  var
+    Res : TJSResponse absolute response;
+
+  begin
+    Result:=False;
+    If (Res.status<>200) then
+      begin
+      If Assigned(aOnError) then
+        aOnError('Error '+IntToStr(Res.Status)+ ': '+Res.StatusText)
+      end
+    else
+      Res.Text._then(
+        function (value : JSValue) : JSValue
+          begin
+          aOnLoaded(String(value));
+          end
+      );
+  end;
+
+  function doFetchFail(response : JSValue) : JSValue;
+
+  begin
+    Result:=False;
+    aOnError('Error 999: unknown error: '+TJSJSON.Stringify(response));
+  end;
+
+begin
+  if ASync then
+    Window.Fetch(aURl)._then(@DoFetchOK).catch(@DoFetchFail)
+  else
+    With TJSXMLHttpRequest.new do
+      begin
+      open('GET', aURL, False);
+      AddEventListener('load',Procedure (oEvent: JSValue)
+        begin
+        aOnLoaded(responseText);
+        end
+      );
+      AddEventListener('error',Procedure (oEvent: JSValue)
+        begin
+        if Assigned(aOnError) then
+          aOnError(TJSError(oEvent).Message);
+        end
+      );
+      send();
+      end;
+end;
+
+class procedure TBrowserLoadHelper.LoadBytes(aURL: String; aSync: Boolean; aOnLoaded: TBytesLoadedCallBack; aOnError: TErrorCallBack);
+
+  function doFetchFail(response : JSValue) : JSValue;
+
+  begin
+    Result:=False;
+    if assigned(aOnError) then
+      if isObject(Response) and (TJSObject(Response) is TJSError) then
+        aOnError('Error 999: '+TJSError(Response).Message)
+      else
+        aOnError('Error 999: unknown error');
+  end;
+
+
+  function doFetchOK(response : JSValue) : JSValue;
+
+  var
+    Res : TJSResponse absolute response;
+
+  begin
+    Result:=False;
+    If (Res.status<>200) then
+      begin
+      If Assigned(aOnError) then
+        aOnError('Error '+IntToStr(Res.Status)+ ': '+Res.StatusText)
+      end
+    else
+      Res.Blob._then(
+        function (value : JSValue) : JSValue
+          begin
+          TJSBlob(Value).ArrayBuffer._then(function(arr : JSValue) : JSValue
+            begin
+            aOnLoaded(TJSArrayBuffer(arr))
+            end
+          ).Catch(@DoFetchFail);
+          end
+        );
+  end;
+
+
+  function StringToArrayBuffer(str : string) : TJSArrayBuffer;
+
+  Var
+    i,l : Integer;
+
+  begin
+    L:=Length(str);
+    Result:=TJSArrayBuffer.New(l*2); // 2 bytes for each char
+    With TJSUint16Array.New(Result) do
+      for i:=1 to L do
+        Values[i-1]:=Ord(Str[i]);
+  end;
+
+begin
+  if ASync then
+    Window.Fetch(aURl)._then(@DoFetchOK).catch(@DoFetchFail)
+  else
+    With TJSXMLHttpRequest.new do
+      begin
+      open('GET', aURL, False);
+      AddEventListener('load',Procedure (oEvent: JSValue)
+        begin
+        if (Status<>200) then
+          begin
+          if assigned(aOnError) then
+            aOnError('Error '+IntToStr(Status)+ ': '+StatusText)
+          end  
+        else
+          aOnLoaded(StringToArrayBuffer(responseText));
+        end
+      );
+      AddEventListener('error',Procedure (oEvent: JSValue)
+        begin
+        if Assigned(aOnError) then
+          aOnError(TJSError(oEvent).Message);
+        end
+      );
+      send();
+      end;
+end;
+
+initialization
+  SetLoadHelperClass(TBrowserLoadHelper);
+end.
+

package/assets/rtl/browserconsole.pas

@@ -0,0 +1,190 @@
+{ Unit that emulates console output in the browser.
+
+  Copyright (C) 2020- Michael Van Canneyt michael@freepascal.org
+
+  This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public
+  License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version
+  with the following modification:
+
+  As a special exception, the copyright holders of this library give you permission to link this library with independent modules
+  to produce an executable, regardless of the license terms of these independent modules,and to copy and distribute the resulting
+  executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions
+  of the license of that module. An independent module is a module which is not derived from or based on this library. If you
+  modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do
+  not wish to do so, delete this exception statement from your version.
+
+  This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.
+
+  You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free
+  Software Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1335, USA.
+}
+{$IFNDEF FPC_DOTTEDUNITS}
+unit browserconsole;
+{$ENDIF}
+
+{$mode objfpc}
+
+interface
+
+uses
+{$IFDEF FPC_DOTTEDUNITS}
+  JSApi.JS, BrowserApi.Web, BrowserApi.LoadHelper, System.SysUtils;
+{$ELSE}
+  js, web, Rtl.BrowserLoadHelper,sysutils;
+{$ENDIF}
+
+
+Const
+  BrowserLineBreak = #10;
+  DefaultMaxConsoleLines = 25;
+  DefaultConsoleStyle = '.pasconsole { '+BrowserLineBreak+
+  'font-family: courier;'+BrowserLineBreak+
+  'font-size: 14px;'+BrowserLineBreak+
+  'background: #FFFFFF;'+BrowserLineBreak+
+  'color: #000000;'+BrowserLineBreak+
+  'display: block;'+BrowserLineBreak+
+  '}';
+  DefaultCRTConsoleStyle = '.pasconsole { '+BrowserLineBreak+
+  'font-family: courier;'+BrowserLineBreak+
+  'font-size: 14px;'+BrowserLineBreak+
+  'background: #000;'+BrowserLineBreak+
+  'color: #14fdce;'+BrowserLineBreak+
+  'display: block;'+BrowserLineBreak+
+  '}';
+
+Var
+  // Element ID for console output. If this is not set, body is used.
+  // If you cange this, call HookConsole.
+  ConsoleElementID : String;
+  // Style to use for console lines. If you change this, call initconsole
+  ConsoleStyle : String;
+  // Style to use for console lines. You can change this at any time.
+  MaxConsoleLines : Integer;
+  // Copy console lines on newline to browser console log
+  ConsoleLinesToBrowserLog : Boolean;
+
+// Clear console content
+Procedure ResetConsole;
+// Re-initialize console (style)
+Procedure InitConsole;
+// Re-hook console
+Procedure HookConsole;
+
+implementation
+
+
+Var
+  LastLine,
+  StyleElement,
+  LinesParent,
+  ConsoleElement : TJSElement;
+
+
+Procedure AppendLine;
+
+Var
+  CurrentCount : Integer;
+  S : TJSNode;
+
+begin
+  CurrentCount:=0;
+  S:=LinesParent.firstChild;
+  While Assigned(S) do
+    begin
+    Inc(CurrentCount);
+    S:=S.nextSibling;
+    end;
+  While CurrentCount>MaxConsoleLines do
+    begin
+    Dec(CurrentCount);
+    LinesParent.removeChild(LinesParent.firstChild);
+    end;
+  LastLine:=Document.createElement('div');
+  LastLine.className:='pasconsole';
+  LinesParent.AppendChild(LastLine);
+end;
+
+
+Function EscapeString(S : String) : String;
+
+Var
+  CL : string;
+
+begin
+  cl:=StringReplace(S,'<','&lt;',[rfReplaceAll]);
+  cl:=StringReplace(cl,'>','&gt;',[rfReplaceAll]);
+  cl:=StringReplace(cl,' ','&nbsp;',[rfReplaceAll]);
+  cl:=StringReplace(cl,#13#10,'<br>',[rfReplaceAll]);
+  cl:=StringReplace(cl,#10,'<br>',[rfReplaceAll]);
+  cl:=StringReplace(cl,#13,'<br>',[rfReplaceAll]);
+  Result:=CL;
+end;
+
+Procedure WriteConsole(S : JSValue; NewLine : Boolean);
+
+Var
+  CL: String;
+
+begin
+  CL:=LastLine.InnerHtml;
+  CL:=CL+EscapeString(String(S));
+  LastLine.InnerHtml:=CL;
+  if NewLine then
+    begin
+    if ConsoleLinesToBrowserLog then
+      console.log(LastLine.InnerText);
+    AppendLine;
+    end;
+end;
+
+Procedure ResetConsole;
+
+
+begin
+  if LinesParent=Nil then exit;
+  While LinesParent.firstElementChild<>Nil do
+    LinesParent.removeChild(LinesParent.firstElementChild);
+  AppendLine;
+end;
+
+Procedure InitConsole;
+
+begin
+  if ConsoleElement=Nil then
+     exit;
+  if (TJSString(ConsoleElement.nodeName).toLowerCase<>'body') then
+     begin
+     While ConsoleElement.firstElementChild<>Nil do
+       ConsoleElement.removeChild(ConsoleElement.firstElementChild);
+     end;
+  StyleElement:=Document.createElement('style');
+  StyleElement.innerText:=ConsoleStyle;
+  ConsoleElement.appendChild(StyleElement);
+  LinesParent:=Document.createElement('div');
+  ConsoleElement.appendChild(LinesParent);
+end;
+
+Procedure HookConsole;
+
+begin
+  ConsoleElement:=Nil;
+  if (ConsoleElementID<>'') then
+    ConsoleElement:=document.getElementById(ConsoleElementID);
+  if (ConsoleElement=Nil) then
+    ConsoleElement:=document.body;
+  if ConsoleElement=Nil then
+    exit;
+  InitConsole;
+  ResetConsole;
+  SetWriteCallBack(@WriteConsole);
+end;
+
+initialization
+  ConsoleLinesToBrowserLog:=True;
+  ConsoleElementID:='pasjsconsole';
+  ConsoleStyle:=DefaultConsoleStyle;
+  MaxConsoleLines:=DefaultMaxConsoleLines;
+  HookConsole;
+end.
+