Exolivelits

.github/workflows/deploy_branches.yml

@@ -60,6 +60,16 @@ jobs:
           eval $(opam env)
           export OPAMYES=1
           opam clean --all-switches --download-cache --logs --repo-cache --unused-repositories
+      - name: Build in-repo external apps (simple-slider)
+        run: |
+          npm ci
+          npm run build -- --base=./
+        working-directory: ./source/external-apps/simple-slider
+      - name: Build in-repo external apps (value-builder)
+        run: |
+          npm ci
+          npm run build -- --base=./
+        working-directory: ./source/external-apps/value-builder
       - name: Setup zarith native BigInt runtime
         run: opam exec -- make setup-zarith
         working-directory: ./source
@@ -68,6 +78,12 @@ jobs:
           export DUNE_CACHE=enabled
           opam exec -- dune build @src/fmt --auto-promote src --profile release
         working-directory: ./source
+      - name: Stage external apps into Hazel www
+        run: |
+          mkdir -p "./source/_build/default/src/web/www/external/exoslider"
+          mkdir -p "./source/_build/default/src/web/www/external/exovaluebuilder"
+          cp -r "./source/external-apps/simple-slider/dist/"* "./source/_build/default/src/web/www/external/exoslider/"
+          cp -r "./source/external-apps/value-builder/dist/"* "./source/_build/default/src/web/www/external/exovaluebuilder/"
       - name: Checkout the website build artifacts repo
         uses: actions/checkout@v4
         with:

HAZEL_EXOLIVELIT_GUIDE.md

@@ -0,0 +1,168 @@
+# Hazel Exo Livelit: External App Integration Guide
+
+Use this guide to make your app embeddable in Hazel as an ExoLivelit. Your app runs in an iframe and communicates with Hazel using `postMessage`. This is a minimal proof of concept implementation; we will be implementing more message types to expose more Hazel functionality, as well as support for incremental syntax updates when it becomes necessary.
+
+This guide has been claude hardened; a claude was able to oneshot adapt an unrelated ts app to an exolivelit and make the relevant hazelside changes by being pointed at this file in an alongside clone of the hazel repo, given additionally a description of how the relevant part of that app's data model should be represented in the JSON format hazel can consume. You can check out the value builder exolivelit to familiarize yourself with the data schema supported.
+
+## Requirements
+
+- **Iframe-compatible**: Your app must work inside an iframe
+- **PostMessage communication**: Follow Hazel's protocol for bidirectional messaging
+- **URL parameters**: Read `id` and `parentOrigin` from query string
+- **Auto-resize**: Measure and report your content dimensions
+- **Value serialization**: Accept initial state and send updated state as stringified JSON
+
+## URL Contract
+
+Hazel loads your app with: `https://your-app/?id=<uuid>&parentOrigin=<hazel-origin>`
+
+- **`id`**: Unique identifier for this projector instance
+- **`parentOrigin`**: Hazel's origin for `postMessage` target (security)
+
+## Message Protocol
+
+### App → Hazel (ToHazelMessage)
+
+To start, it suffices to send `ready` and `setSyntax`, and to handle `init`. More of the internal livelits API will be exposed here in the future.
+
+```typescript
+type ToHazelMessage =
+  | { type: "ready"; id: string } // Sent on mount
+  | { type: "setSyntax"; id: string; codec: string; value: string } // Send edits
+  | { type: "resize"; id: string; width: number; height: number }; // Report size
+```
+
+### Hazel → App (FromHazelMessage)
+
+```typescript
+type FromHazelMessage =
+  | { type: "init"; id: string; value: string } // Initial value
+  | {
+      type: "constraints";
+      id: string;
+      maxWidth: number;
+      maxHeight: number;
+      minWidth?: number;
+      minHeight?: number;
+    }; // Size limits
+```
+
+## Communication Lifecycle
+
+1. **App mounts** → sends `{type: 'ready', id}`
+2. **Hazel responds** → `{type: 'init', value: "..."}` + `{type: 'constraints', ...}`
+3. **App applies constraints** → sets `maxWidth` CSS, starts auto-resize
+4. **User edits** → app sends `{type: 'setSyntax', codec: 'json', value: JSON.stringify(newValue)}`
+5. **Content grows** → app sends `{type: 'resize', width, height}` (debounced)
+
+## Integration Starter Library
+
+Copy these **3 files** into your e.g. `src/hooks/` directory:
+
+### 1. Core Hook (`hazel-integration-base.ts`)
+
+### 2. Resize Strategies (`resize-strategies.ts`)
+
+### 3. App-Specific Hook (`useHazelIntegration.ts`)
+
+```
+src/
+├── components/
+│   └── MyEditor.tsx            # Core app logic (Hazel-agnostic)
+├── hooks/
+│   ├── hazel-integration-base.ts   # Shared base hook
+│   ├── resize-strategies.ts        # Resize implementations
+│   └── useHazelIntegration.ts      # App-specific wrapper
+└── App.tsx                     # Entry point, uses Hazel integration
+```
+
+## App Integration Example
+
+```typescript
+// App.tsx
+import { useState } from "react";
+import { useHazelIntegration } from "./useHazelIntegration";
+
+export default function App() {
+  const urlParams = new URLSearchParams(window.location.search);
+  const id = urlParams.get("id") || "local-demo";
+  const [value, setValue] = useState<any>(0);
+
+  const { setSyntax } = useHazelIntegration({
+    id,
+    codec: "json" /* The only codec supported for now  */,
+    onInit: (valueStr) => {
+      setValue(JSON.parse(valueStr));
+    },
+    onConstraints: (c) => {
+      document.body.style.maxWidth = `${c.maxWidth}px`;
+    },
+  });
+
+  const handleChange = (newValue: any) => {
+    setSyntax(JSON.stringify(newValue));
+  };
+
+  return (
+    <div style={{}}>
+      <h3>My Hazel-Embedded App</h3>
+      {/* Your editor UI here */}
+      <button onClick={() => handleChange(value + 1)}>
+        Increment: {value}
+      </button>
+    </div>
+  );
+}
+```
+
+## CSS Guidelines
+
+**DO:**
+
+- Use flexible, responsive layouts (`flex`, `grid`)
+- Allow content-driven height (`min-height` instead of fixed `height`)
+- Apply `maxWidth` from constraints for responsive behavior
+
+**DON'T:**
+
+- Set fixed `height: 100vh` on root containers
+- Use viewport units that ignore iframe constraints
+- Create horizontal scrolling (respect `maxWidth`)
+
+## Hazel Integration (Hazel-side)
+
+We don't currently support dynamic registration for new kinds of exolivelit, although there is no particular blocker to doing so. Right now to add a new one, you'll need to clone the hazel repo and change two definitions in the `Exo.re` file.
+
+### 1. Create a static identifier for your exolivelit
+
+Add YourApp to the `Exo.kind` type. This will determine the Hazel UI name of your exolivelit.
+
+```ocaml
+  type kind =
+  | ...
+  | YourApp;
+```
+
+### 2. Specify static and default properties for your exolivelit
+
+Add a corresponding case to the `Exo.module_of_kind` function. This requires a `prod` and option `dev` URL for your app. The `shape` property determines how the text flow resumes to the right of your livelit; pick `Block` if in doubt. The rest of the properties (`guard` and `size`) are work-in-progress and will likely be set dynamically via content negoiation in the future; copying the values below should suffice for a prototype.
+
+```ocaml
+  | YourApp => {
+      kind,
+      prod: "https://yourdomain.com", (* Your public URL for the app *)
+      dev: "http://localhost:port", (* Your internal dev path, if applicable *)
+      shape: Block, (* Block: After livelit, text flow continues from bottom line. Tab: Continues from top *)
+      guard: _ => true, (* Determines what Hazel syntax your app can be applied to; okay to leave as this for now *)
+      size: {
+        width: 680, (* init width in px; *)
+        height: 490, (* init height in px *)
+      },
+    }
+```
+
+## Example Apps
+
+- **`external-apps/simple-slider/`**: Integer slider
+- **`external-apps/value-builder/`**: Compositional Hazel value editor
+- **`https://github.com/disconcision/nool/pull/4`**: A PR updating a math toy to support livelit embedding

external-apps/simple-slider/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

external-apps/simple-slider/README.md

@@ -0,0 +1,99 @@
+# Simple Slider - External Hazel GUI
+
+A standalone React TypeScript slider component designed to integrate with the Hazel editor as an external projector.
+
+## Features
+
+- **Integer Slider**: Interactive range input for integer values
+- **Hazel Integration**: Implements postMessage protocol for seamless communication with Hazel
+- **Multiple Variants**: Different slider configurations (basic, small range, large range)
+- **Responsive Design**: Clean, modern UI that works well in iframes
+- **Type Safety**: Full TypeScript support
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+## Development
+
+The app will run at `http://localhost:5173` by default. You can view it standalone in your browser or embed it in an iframe for testing the Hazel integration.
+
+### Hazel Integration Protocol
+
+The slider implements a postMessage-based protocol for communication with Hazel:
+
+#### Messages sent to Hazel (parent):
+
+- `ready` - Component is loaded and ready
+- `setSyntax` - User changed the slider value (includes codec and new value)
+- `resize` - Component wants to change its size (future feature)
+- `requestFocus` - Component wants focus (future feature)
+
+#### Messages received from Hazel (parent):
+
+- `init` - Initial value when projector is created
+- `update` - Value changed externally (e.g., user edited the underlying syntax)
+
+#### Codec
+
+The slider uses the `int` codec, which converts between:
+
+- **Hazel side**: `Atom(Int(Bigint.t))` (integer literal in the AST)
+- **JSON**: String representation of the integer (e.g., `"42"`)
+
+## Integration with Hazel
+
+When integrated with Hazel, this component will:
+
+1. **Replace integer literals** in the editor with an interactive slider
+2. **Receive initial value** from the underlying Hazel syntax
+3. **Send updates** back to Hazel when the user moves the slider
+4. **Stay in sync** when the underlying syntax changes externally
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── IntegerSlider.tsx    # Main slider component
+│   └── IntegerSlider.css    # Slider styles
+├── hooks/
+│   └── useHazelIntegration.ts  # Hazel communication hook
+├── types/
+│   └── hazel-protocol.ts    # TypeScript types for the protocol
+├── App.tsx                  # Main app with demo
+├── App.css                  # App-level styles
+└── main.tsx                 # Entry point
+```
+
+## Building for Production
+
+```bash
+npm run build
+```
+
+The built files will be in the `dist/` directory. For Hazel integration, these files can be:
+
+- Served from a static web server
+- Copied into Hazel's `src/web/www/external/simple-slider/` directory
+- Served via Hazel's Vite development server
+
+## Next Steps
+
+1. **Test standalone** - Verify the slider works in your browser
+2. **Hazel iframe wrapper** - Create a projector that embeds this in an iframe
+3. **Message bridge** - Add global postMessage handler in Hazel
+4. **Codec implementation** - Add int literal ↔ JSON conversion in Hazel
+5. **Integration testing** - Test the full round-trip communication

external-apps/simple-slider/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { globalIgnores } from 'eslint/config'
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs['recommended-latest'],
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

external-apps/simple-slider/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + React + TS</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>