docs

Author: gunta

.github/workflows/deploy.yml

@@ -0,0 +1,63 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.1.36'
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Determine base path
+        id: pages
+        run: |
+          REPO_NAME="${GITHUB_REPOSITORY#*/}"
+          if [[ "$REPO_NAME" == *.github.io ]]; then
+            echo "base_path=" >>"$GITHUB_OUTPUT"
+          else
+            echo "base_path=/$REPO_NAME" >>"$GITHUB_OUTPUT"
+          fi
+
+      - name: Build static site
+        run: bun run docs:build
+        env:
+          NEXT_PUBLIC_BASE_PATH: "${{ steps.pages.outputs.base_path }}"
+          NEXT_TELEMETRY_DISABLED: '1'
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./out
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.source/index.ts

@@ -1,6 +1,23 @@
 // @ts-nocheck -- skip type checking
-import * as docs_1 from "../content/docs/test.mdx?collection=docs&hash=1760316941584"
-import * as docs_0 from "../content/docs/index.mdx?collection=docs&hash=1760316941584"
+import * as docs_18 from "../content/docs/spec/typing.mdx?collection=docs&hash=1760326440684"
+import * as docs_17 from "../content/docs/spec/stdlib.mdx?collection=docs&hash=1760326440684"
+import * as docs_16 from "../content/docs/spec/state-machines.mdx?collection=docs&hash=1760326440684"
+import * as docs_15 from "../content/docs/spec/security.mdx?collection=docs&hash=1760326440684"
+import * as docs_14 from "../content/docs/spec/prompting.mdx?collection=docs&hash=1760326440684"
+import * as docs_13 from "../content/docs/spec/productivity.mdx?collection=docs&hash=1760326440684"
+import * as docs_12 from "../content/docs/spec/llm-signatures.mdx?collection=docs&hash=1760326440684"
+import * as docs_11 from "../content/docs/spec/language.mdx?collection=docs&hash=1760326440684"
+import * as docs_10 from "../content/docs/spec/grammar.mdx?collection=docs&hash=1760326440684"
+import * as docs_9 from "../content/docs/spec/errors.mdx?collection=docs&hash=1760326440684"
+import * as docs_8 from "../content/docs/spec/effects.mdx?collection=docs&hash=1760326440684"
+import * as docs_7 from "../content/docs/spec/contracts-proofs.mdx?collection=docs&hash=1760326440684"
+import * as docs_6 from "../content/docs/guides/svelte.mdx?collection=docs&hash=1760326440684"
+import * as docs_5 from "../content/docs/guides/react.mdx?collection=docs&hash=1760326440684"
+import * as docs_4 from "../content/docs/guides/compile-to-typescript.mdx?collection=docs&hash=1760326440684"
+import * as docs_3 from "../content/docs/guides/compile-to-rescript.mdx?collection=docs&hash=1760326440684"
+import * as docs_2 from "../content/docs/test.mdx?collection=docs&hash=1760326440684"
+import * as docs_1 from "../content/docs/index.mdx?collection=docs&hash=1760326440684"
+import * as docs_0 from "../content/docs/examples.mdx?collection=docs&hash=1760326440684"
 import { _runtime } from "fumadocs-mdx/runtime/next"
 import * as _source from "../source.config"
-export const docs = _runtime.docs<typeof _source.docs>([{ info: {"path":"index.mdx","fullPath":"content/docs/index.mdx"}, data: docs_0 }, { info: {"path":"test.mdx","fullPath":"content/docs/test.mdx"}, data: docs_1 }], [])
+export const docs = _runtime.docs<typeof _source.docs>([{ info: {"path":"examples.mdx","fullPath":"content/docs/examples.mdx"}, data: docs_0 }, { info: {"path":"index.mdx","fullPath":"content/docs/index.mdx"}, data: docs_1 }, { info: {"path":"test.mdx","fullPath":"content/docs/test.mdx"}, data: docs_2 }, { info: {"path":"guides/compile-to-rescript.mdx","fullPath":"content/docs/guides/compile-to-rescript.mdx"}, data: docs_3 }, { info: {"path":"guides/compile-to-typescript.mdx","fullPath":"content/docs/guides/compile-to-typescript.mdx"}, data: docs_4 }, { info: {"path":"guides/react.mdx","fullPath":"content/docs/guides/react.mdx"}, data: docs_5 }, { info: {"path":"guides/svelte.mdx","fullPath":"content/docs/guides/svelte.mdx"}, data: docs_6 }, { info: {"path":"spec/contracts-proofs.mdx","fullPath":"content/docs/spec/contracts-proofs.mdx"}, data: docs_7 }, { info: {"path":"spec/effects.mdx","fullPath":"content/docs/spec/effects.mdx"}, data: docs_8 }, { info: {"path":"spec/errors.mdx","fullPath":"content/docs/spec/errors.mdx"}, data: docs_9 }, { info: {"path":"spec/grammar.mdx","fullPath":"content/docs/spec/grammar.mdx"}, data: docs_10 }, { info: {"path":"spec/language.mdx","fullPath":"content/docs/spec/language.mdx"}, data: docs_11 }, { info: {"path":"spec/llm-signatures.mdx","fullPath":"content/docs/spec/llm-signatures.mdx"}, data: docs_12 }, { info: {"path":"spec/productivity.mdx","fullPath":"content/docs/spec/productivity.mdx"}, data: docs_13 }, { info: {"path":"spec/prompting.mdx","fullPath":"content/docs/spec/prompting.mdx"}, data: docs_14 }, { info: {"path":"spec/security.mdx","fullPath":"content/docs/spec/security.mdx"}, data: docs_15 }, { info: {"path":"spec/state-machines.mdx","fullPath":"content/docs/spec/state-machines.mdx"}, data: docs_16 }, { info: {"path":"spec/stdlib.mdx","fullPath":"content/docs/spec/stdlib.mdx"}, data: docs_17 }, { info: {"path":"spec/typing.mdx","fullPath":"content/docs/spec/typing.mdx"}, data: docs_18 }], [{"info":{"path":"meta.json","fullPath":"content/docs/meta.json"},"data":{"title":"Docs"}}, {"info":{"path":"guides/meta.json","fullPath":"content/docs/guides/meta.json"},"data":{"title":"Guides"}}, {"info":{"path":"spec/meta.json","fullPath":"content/docs/spec/meta.json"},"data":{"title":"Specification"}}])

.source/source.config.mjs

@@ -5,6 +5,16 @@ import {
   frontmatterSchema,
   metaSchema
 } from "fumadocs-mdx/config";
+import fs from "node:fs";
+import path from "node:path";
+import { bundledLanguages } from "shiki";
+var shikiGrammarDir = path.join(process.cwd(), "lib/shiki");
+var betterscriptGrammar = JSON.parse(
+  fs.readFileSync(path.join(shikiGrammarDir, "betterscript.tmLanguage.json"), "utf8")
+);
+var ebnfGrammar = JSON.parse(
+  fs.readFileSync(path.join(shikiGrammarDir, "ebnf.tmLanguage.json"), "utf8")
+);
 var docs = defineDocs({
   docs: {
     schema: frontmatterSchema,
@@ -18,7 +28,38 @@ var docs = defineDocs({
 });
 var source_config_default = defineConfig({
   mdxOptions: {
-    // MDX options
+    remarkCodeTabOptions: {
+      parseMdx: true
+    },
+    // Enable custom Shiki language for betterscript
+    rehypeCodeOptions: {
+      themes: {
+        light: "github-light",
+        dark: "github-dark"
+      },
+      langs: [
+        ...Object.keys(bundledLanguages),
+        {
+          // Minimal TextMate grammar to keep ```ebnf``` fences rendering without errors
+          ...ebnfGrammar
+        },
+        {
+          // Shiki custom language object, loaded from local TextMate grammar
+          aliases: ["bs"],
+          name: "betterscript",
+          scopeName: "source.betterscript",
+          // Merge the grammar JSON
+          ...betterscriptGrammar
+        }
+      ],
+      langAlias: {
+        bs: "betterscript",
+        rescript: "purescript",
+        ReScript: "purescript",
+        res: "purescript",
+        text: "ebnf"
+      }
+    }
   }
 });
 export {

README.md

@@ -1,45 +1,20 @@
-# betterscript-docs
+# BetterScript
 
-This is a Next.js application generated with
-[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+LLM-first language with deterministic semantics, compiling to ReScript and TypeScript.
 
-Run development server:
+## Docs
 
-```bash
-npm run dev
-# or
-pnpm dev
-# or
-yarn dev
-```
-
-Open http://localhost:3000 with your browser to see the result.
-
-## Explore
-
-In the project, you can see:
-
-- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
-- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep.
-
-| Route                     | Description                                            |
-| ------------------------- | ------------------------------------------------------ |
-| `app/(home)`              | The route group for your landing page and other pages. |
-| `app/docs`                | The documentation layout and pages.                    |
-| `app/api/search/route.ts` | The Route Handler for search.                          |
+- Full specification lives under `content/docs` and is served at `/docs`.
+  - Start at `content/docs/index.mdx`.
 
-### Fumadocs MDX
+## Develop
 
-A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
-
-Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
-
-## Learn More
+```bash
+bun run docs:dev
+```
 
-To learn more about Next.js and Fumadocs, take a look at the following
-resources:
+## Build
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
-  features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs
+```bash
+bun run docs:build
+```

content/concept.mdx

@@ -37,3 +37,4 @@ Pre-Commit Hooks
 Build Speed
 Errors with Suggestions
 Embeded Open Telemetry
+

content/docs/examples.mdx

@@ -0,0 +1,37 @@
+---
+title: Examples
+description: End-to-end examples demonstrating intents, effects, agents, and contracts.
+---
+
+## Chat Summarizer
+
+```betterscript
+intent Summarize [text: string] -> [summary: string]
+
+effect LLM { fn complete(prompt: string): Task<string> }
+
+fn summarize(i: Summarize) with LLM: Task<{ summary: string }> {
+  let prompt = "Summarize: " ++ i.text
+  let out = await LLM.complete(prompt)
+  { summary: out }
+}
+```
+
+TypeScript:
+
+```ts
+type LLM = { complete: (prompt: string) => Promise<string> };
+async function summarize(i: { text: string }, LLM: LLM): Promise<{ summary: string }> {
+  const out = await LLM.complete(`Summarize: ${i.text}`);
+  return { summary: out };
+}
+```
+
+## Counter Agent + Machine
+
+```betterscript
+agent Counter(0) { state count: int = 0; on inc(n: int): int { count = count + n; count } }
+machine CounterUI { /* ... UI events ... */ }
+```
+
+

content/docs/guides/compile-to-rescript.mdx

@@ -0,0 +1,44 @@
+---
+title: Compile to ReScript
+description: Semantic mapping and examples from BetterScript to ReScript.
+---
+
+## Types
+
+```betterscript
+type Id = Id(string)
+type User = { id: Id, name: string }
+```
+
+```rescript
+type id = Id(string)
+type user = { id: id, name: string }
+```
+
+## Variants & Match
+
+```betterscript
+type Purchase = Granted(User) | Denied(string)
+fn access(p: Purchase): bool { match p { Granted(_) -> true | Denied(_) -> false } }
+```
+
+```rescript
+type purchase = Granted(user) | Denied(string)
+let access = (p: purchase): bool => switch p { | Granted(_) => true | Denied(_) => false }
+```
+
+## Modules
+
+```betterscript
+module Math { export fn add(a: int, b: int): int { a + b } }
+```
+
+```rescript
+module Math = { let add = (a: int, b: int): int => a + b }
+```
+
+## Effects & Tasks
+
+Model effects via module capabilities; tasks via `Js.Promise`.
+
+

content/docs/guides/compile-to-typescript.mdx

@@ -0,0 +1,49 @@
+---
+title: Compile to TypeScript
+description: Mapping BetterScript constructs to idiomatic TypeScript.
+---
+
+## ADTs
+
+```betterscript
+type Purchase = Granted(user: User) | Denied(reason: string)
+```
+
+```ts
+type Purchase =
+  | { tag: "Granted"; user: User }
+  | { tag: "Denied"; reason: string };
+```
+
+## Pattern Matching
+
+```betterscript
+fn describe(p: Purchase): string {
+  match p { Granted(user: u) -> u.name | Denied(reason: r) -> r }
+}
+```
+
+```ts
+function describe(p: Purchase): string {
+  switch (p.tag) {
+    case "Granted": return p.user.name;
+    case "Denied": return p.reason;
+  }
+}
+```
+
+## Async & Parallel
+
+```betterscript
+let [a,b] = await parallel (fa(), fb())
+```
+
+```ts
+const [a, b] = await Promise.all([fa(), fb()]);
+```
+
+## Contracts
+
+Runtime checks emitted behind feature flag; Zod optional for external IO.
+
+

content/docs/guides/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Guides",
+  "order": [
+    "compile-to-rescript",
+    "compile-to-typescript",
+    "react",
+    "svelte"
+  ]
+}
+

content/docs/guides/react.mdx

@@ -0,0 +1,28 @@
+---
+title: React Interop
+description: Using BetterScript modules and ADTs from React.
+---
+
+## Components
+
+```betterscript
+type Model = Loading | Ready(data: string) | Error(msg: string)
+
+module UI {
+  export fn view(m: Model): ReactNode { /* compiled TSX */ }
+}
+```
+
+TypeScript component consuming ADT:
+
+```tsx
+function View(props: { m: Model }) {
+  switch (props.m.tag) {
+    case "Loading": return <Spinner/>;
+    case "Ready": return <div>{props.m.data}</div>;
+    case "Error": return <Error msg={props.m.msg}/>;
+  }
+}
+```
+
+