From 5621b0d2ddfdd8d40ab2115ef99744076bf991c0 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Fri, 12 Jun 2026 14:19:24 -0400
Subject: [PATCH 1/2] feat(playground-url): add package to generate playground
 share links

Add @opendatacapture/playground-url, which encodes an instrument's source
files into a shareable playground link (lz-string compressed, matching the
playground's existing URL scheme). Exposes a library (generatePlaygroundURL,
encodeShareURL, decodeShareURL, isFullscreenShareURL) and a `playground-url`
CLI that points at an instrument directory and emits the link.

Move the share-URL encode/decode logic out of apps/playground into the new
package so the app and CLI share one implementation, and have the playground
consume it (passing baseURL: window.location.origin to preserve dev behavior).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/playground/package.json                  |   2 +-
 .../Header/ShareButton/ShareButton.tsx        |  15 ++-
 apps/playground/src/pages/IndexPage.tsx       |   2 +-
 apps/playground/src/utils/encode.ts           |  46 --------
 packages/playground-url/README.md             |  46 ++++++++
 packages/playground-url/package.json          |  40 +++++++
 packages/playground-url/scripts/build.js      |  34 ++++++
 packages/playground-url/src/cli.ts            | 108 ++++++++++++++++++
 packages/playground-url/src/index.ts          |  10 ++
 packages/playground-url/src/models.ts         |  20 ++++
 packages/playground-url/src/share-url.test.ts |  60 ++++++++++
 packages/playground-url/src/share-url.ts      |  73 ++++++++++++
 packages/playground-url/tsconfig.json         |   7 ++
 packages/playground-url/vitest.config.ts      |  13 +++
 pnpm-lock.yaml                                |  25 +++-
 15 files changed, 447 insertions(+), 54 deletions(-)
 delete mode 100644 apps/playground/src/utils/encode.ts
 create mode 100644 packages/playground-url/README.md
 create mode 100644 packages/playground-url/package.json
 create mode 100644 packages/playground-url/scripts/build.js
 create mode 100644 packages/playground-url/src/cli.ts
 create mode 100644 packages/playground-url/src/index.ts
 create mode 100644 packages/playground-url/src/models.ts
 create mode 100644 packages/playground-url/src/share-url.test.ts
 create mode 100644 packages/playground-url/src/share-url.ts
 create mode 100644 packages/playground-url/tsconfig.json
 create mode 100644 packages/playground-url/vitest.config.ts

diff --git a/apps/playground/package.json b/apps/playground/package.json
index a5133a021..5125538d0 100644
--- a/apps/playground/package.json
+++ b/apps/playground/package.json
@@ -17,6 +17,7 @@
     "@douglasneuroinformatics/libui": "catalog:",
     "@monaco-editor/react": "^4.7.0",
     "@opendatacapture/instrument-bundler": "workspace:*",
+    "@opendatacapture/playground-url": "workspace:*",
     "@opendatacapture/react-core": "workspace:*",
     "@opendatacapture/runtime-core": "workspace:*",
     "@opendatacapture/runtime-v1": "workspace:*",
@@ -31,7 +32,6 @@
     "jwt-decode": "^4.0.0",
     "lodash-es": "workspace:lodash-es__4.x@*",
     "lucide-react": "^0.503.0",
-    "lz-string": "^1.5.0",
     "monaco-editor": "^0.52.2",
     "motion": "catalog:",
     "neverthrow": "catalog:",
diff --git a/apps/playground/src/components/Header/ShareButton/ShareButton.tsx b/apps/playground/src/components/Header/ShareButton/ShareButton.tsx
index 1e21f3731..7f2430539 100644
--- a/apps/playground/src/components/Header/ShareButton/ShareButton.tsx
+++ b/apps/playground/src/components/Header/ShareButton/ShareButton.tsx
@@ -3,18 +3,20 @@ import { useEffect, useState } from 'react';
 import { formatByteSize } from '@douglasneuroinformatics/libjs';
 import { Heading, Input, Label, Popover, Tooltip } from '@douglasneuroinformatics/libui/components';
 import { useTranslation } from '@douglasneuroinformatics/libui/hooks';
+import { encodeShareURL } from '@opendatacapture/playground-url';
 import { CopyButton } from '@opendatacapture/react-core';
 import { CircleHelpIcon, Share2Icon } from 'lucide-react';
 
 import { useFilesRef } from '@/hooks/useFilesRef';
 import { useAppStore } from '@/store';
-import { encodeShareURL } from '@/utils/encode';
 
 export const ShareButton = () => {
   const label = useAppStore((store) => store.selectedInstrument.label);
   const editorFilesRef = useFilesRef();
   const [isFullscreen, setIsFullscreen] = useState(false);
-  const [shareURL, setShareURL] = useState(encodeShareURL({ files: editorFilesRef.current, label }));
+  const [shareURL, setShareURL] = useState(
+    encodeShareURL({ baseURL: window.location.origin, files: editorFilesRef.current, label })
+  );
   const [isPopoverOpen, setIsPopoverOpen] = useState(false);
   const [isTooltipOpen, setIsTooltipOpen] = useState(false);
   const { t } = useTranslation();
@@ -22,7 +24,14 @@ export const ShareButton = () => {
   // The user cannot modify the editor without closing the popover
   useEffect(() => {
     if (isPopoverOpen) {
-      setShareURL(encodeShareURL({ files: editorFilesRef.current, fullscreen: isFullscreen, label }));
+      setShareURL(
+        encodeShareURL({
+          baseURL: window.location.origin,
+          files: editorFilesRef.current,
+          fullscreen: isFullscreen,
+          label
+        })
+      );
     }
   }, [isFullscreen, isPopoverOpen, label]);
 
diff --git a/apps/playground/src/pages/IndexPage.tsx b/apps/playground/src/pages/IndexPage.tsx
index c8428ea64..c0fe61ace 100644
--- a/apps/playground/src/pages/IndexPage.tsx
+++ b/apps/playground/src/pages/IndexPage.tsx
@@ -1,6 +1,7 @@
 import { useEffect } from 'react';
 
 import { LanguageToggle, Separator, ThemeToggle } from '@douglasneuroinformatics/libui/components';
+import { decodeShareURL, isFullscreenShareURL } from '@opendatacapture/playground-url';
 import esbuildWasmUrl from 'esbuild-wasm/esbuild.wasm?url';
 
 import { Header } from '@/components/Header';
@@ -8,7 +9,6 @@ import { MainContent } from '@/components/MainContent';
 import { Viewer } from '@/components/Viewer';
 import type { InstrumentRepository } from '@/models/instrument-repository.model';
 import { useAppStore } from '@/store';
-import { decodeShareURL, isFullscreenShareURL } from '@/utils/encode';
 
 const { initialize } = await import('esbuild-wasm');
 await initialize({
diff --git a/apps/playground/src/utils/encode.ts b/apps/playground/src/utils/encode.ts
deleted file mode 100644
index 4705155c5..000000000
--- a/apps/playground/src/utils/encode.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { compressToEncodedURIComponent, decompressFromEncodedURIComponent } from 'lz-string';
-import { z } from 'zod/v4';
-
-import { $EditorFile } from '@/models/editor-file.model';
-import type { EditorFile } from '@/models/editor-file.model';
-import type { InstrumentRepository } from '@/models/instrument-repository.model';
-
-type ShareURL = URL & { size: number };
-
-const $EditorFiles = z.array($EditorFile);
-
-function decodeFiles(encodedFiles: string): EditorFile[] {
-  return $EditorFiles.parse(JSON.parse(decompressFromEncodedURIComponent(encodedFiles)));
-}
-
-function encodeFiles(files: EditorFile[]): string {
-  return compressToEncodedURIComponent(JSON.stringify($EditorFiles.parse(files)));
-}
-
-export function encodeShareURL({
-  files,
-  fullscreen,
-  label
-}: Pick<InstrumentRepository, 'files' | 'label'> & { fullscreen?: boolean }): ShareURL {
-  const url = new URL(location.origin) as ShareURL;
-  url.searchParams.append('files', encodeFiles(files));
-  url.searchParams.append('label', compressToEncodedURIComponent(label));
-  if (fullscreen) {
-    url.searchParams.append('fullscreen', '1');
-  }
-  url.size = new TextEncoder().encode(url.href).length;
-  return url;
-}
-
-export function isFullscreenShareURL(url: URL): boolean {
-  return url.searchParams.get('fullscreen') === '1';
-}
-
-export function decodeShareURL(url: URL): null | Pick<InstrumentRepository, 'files' | 'label'> {
-  const encodedFiles = url.searchParams.get('files');
-  const encodedLabel = url.searchParams.get('label');
-  if (!(encodedFiles && encodedLabel)) {
-    return null;
-  }
-  return { files: decodeFiles(encodedFiles), label: decompressFromEncodedURIComponent(encodedLabel) };
-}
diff --git a/packages/playground-url/README.md b/packages/playground-url/README.md
new file mode 100644
index 000000000..c9a232d56
--- /dev/null
+++ b/packages/playground-url/README.md
@@ -0,0 +1,46 @@
+# @opendatacapture/playground-url
+
+Generate shareable [Open Data Capture playground](https://playground.opendatacapture.org) links from instrument source files.
+
+A playground link embeds a snapshot of an instrument's source files directly in the URL (lz-string compressed). Anyone who opens the link gets that instrument loaded into the playground — no server or account required.
+
+## Library
+
+```ts
+import { generatePlaygroundURL } from '@opendatacapture/playground-url';
+
+const url = generatePlaygroundURL({
+  files: [{ name: 'index.ts', content: 'export default { /* ... */ };' }],
+  label: 'My Instrument'
+});
+// => https://playground.opendatacapture.org/?files=...&label=...
+```
+
+| Export                           | Description                                                 |
+| -------------------------------- | ----------------------------------------------------------- |
+| `generatePlaygroundURL(options)` | Returns the share link as a string.                         |
+| `encodeShareURL(options)`        | Returns a `URL` annotated with the encoded `size` in bytes. |
+| `decodeShareURL(url)`            | Decodes an instrument from a share URL (or `null`).         |
+| `isFullscreenShareURL(url)`      | Whether the link opens the read-only fullscreen preview.    |
+| `DEFAULT_PLAYGROUND_URL`         | Origin of the hosted playground.                            |
+
+Options: `files`, `label`, optional `fullscreen` (read-only preview) and `baseURL` (defaults to the hosted playground).
+
+## CLI
+
+Point it at a directory of instrument source files:
+
+```sh
+npx @opendatacapture/playground-url ./my-instrument
+```
+
+The status line is written to stderr and the link to stdout, so it pipes cleanly.
+
+| Option                 | Description                                                       |
+| ---------------------- | ----------------------------------------------------------------- |
+| `-l, --label <label>`  | Label for the shared instrument (defaults to the directory name). |
+| `-f, --fullscreen`     | Share a read-only fullscreen preview instead of the editor.       |
+| `-b, --base-url <url>` | Playground origin to link to (defaults to the hosted playground). |
+| `-o, --open`           | Open the generated link in your default browser.                  |
+
+Only text source files (`.css`, `.html`, `.js`, `.jsx`, `.json`, `.ts`, `.tsx`) are embedded; binary assets cannot be represented in a share URL and are skipped with a warning.
diff --git a/packages/playground-url/package.json b/packages/playground-url/package.json
new file mode 100644
index 000000000..923a7efc8
--- /dev/null
+++ b/packages/playground-url/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "@opendatacapture/playground-url",
+  "type": "module",
+  "version": "2.0.0",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DouglasNeuroInformatics/OpenDataCapture.git",
+    "directory": "packages/playground-url"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "playground-url": "./dist/cli.js"
+  },
+  "files": [
+    "!/src/**/*.test.ts",
+    "/dist",
+    "/src"
+  ],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "format": "prettier --write src",
+    "lint": "tsc && eslint --fix src",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "catalog:",
+    "lz-string": "^1.5.0",
+    "zod": "workspace:zod__3.x@*"
+  },
+  "devDependencies": {
+    "esbuild": "catalog:"
+  }
+}
diff --git a/packages/playground-url/scripts/build.js b/packages/playground-url/scripts/build.js
new file mode 100644
index 000000000..baa189336
--- /dev/null
+++ b/packages/playground-url/scripts/build.js
@@ -0,0 +1,34 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import * as esbuild from 'esbuild';
+
+const outdir = path.resolve(import.meta.dirname, '../dist');
+
+await fs.promises.rm(outdir, { force: true, recursive: true });
+
+// Bundle dependencies into a self-contained CLI so it runs via `npx` without a
+// node_modules resolution step, and so esbuild handles the CJS/ESM interop of
+// dependencies like lz-string. Node built-ins are left external automatically.
+await esbuild.build({
+  banner: {
+    // Shim `require`/`__dirname`/`__filename` so bundled CommonJS dependencies
+    // (e.g. commander) work in the ESM output.
+    js: [
+      '#!/usr/bin/env node',
+      'import { createRequire as __createRequire } from "node:module";',
+      'Object.defineProperties(globalThis, {',
+      '  __dirname: { value: import.meta.dirname, writable: false },',
+      '  __filename: { value: import.meta.filename, writable: false },',
+      '  require: { value: __createRequire(import.meta.url), writable: false }',
+      '});'
+    ].join('\n')
+  },
+  bundle: true,
+  entryPoints: [path.resolve(import.meta.dirname, '../src/cli.ts')],
+  format: 'esm',
+  minify: false,
+  outdir,
+  platform: 'node',
+  target: ['node22', 'es2022']
+});
diff --git a/packages/playground-url/src/cli.ts b/packages/playground-url/src/cli.ts
new file mode 100644
index 000000000..0a2ad5626
--- /dev/null
+++ b/packages/playground-url/src/cli.ts
@@ -0,0 +1,108 @@
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import chalk from 'chalk';
+import { Command, InvalidArgumentError } from 'commander';
+
+import { name, version } from '../package.json';
+import { DEFAULT_PLAYGROUND_URL, encodeShareURL } from './share-url.js';
+
+import type { EditorFile } from './models.js';
+
+/** Text files the playground can load from a share URL. */
+const TEXT_FILE_EXT_REGEX = /\.(css|html|js|jsx|json|ts|tsx)$/i;
+/** Bundler assets that exist on disk but cannot be embedded in a (string-only) share URL. */
+const BINARY_FILE_EXT_REGEX = /\.(jpeg|jpg|mp3|mp4|png|svg|webp)$/i;
+
+function parseTarget(target: string): string {
+  const resolved = path.resolve(target);
+  if (!fs.existsSync(resolved)) {
+    throw new InvalidArgumentError('Directory does not exist');
+  }
+  if (!fs.lstatSync(resolved).isDirectory()) {
+    throw new InvalidArgumentError('Not a directory');
+  }
+  return resolved;
+}
+
+function parseBaseURL(value: string): string {
+  try {
+    return new URL(value).origin;
+  } catch {
+    throw new InvalidArgumentError(`Not a valid URL: ${value}`);
+  }
+}
+
+/** Read every URL-shareable text file directly within `target`, warning about skipped assets. */
+function readInstrumentFiles(target: string): EditorFile[] {
+  const files: EditorFile[] = [];
+  for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+    if (!entry.isFile()) {
+      continue;
+    }
+    const filepath = path.join(target, entry.name);
+    if (TEXT_FILE_EXT_REGEX.test(entry.name)) {
+      files.push({ content: fs.readFileSync(filepath, 'utf-8'), name: entry.name });
+    } else if (BINARY_FILE_EXT_REGEX.test(entry.name)) {
+      process.stderr.write(
+        chalk.yellow(`⚠ Skipping '${entry.name}': binary assets cannot be embedded in a share URL\n`)
+      );
+    }
+  }
+  return files;
+}
+
+/** Open a URL in the user's default browser, cross-platform, without extra dependencies. */
+function openInBrowser(url: string): void {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  spawn(command, [url], { detached: true, shell: process.platform === 'win32', stdio: 'ignore' }).unref();
+}
+
+const program = new Command();
+
+program
+  .name(name)
+  .description('Generate an Open Data Capture playground link from an instrument directory')
+  .version(version)
+  .allowExcessArguments(false)
+  .argument('<target>', 'the directory containing the instrument source files', parseTarget)
+  .option('-l, --label <label>', 'the label for the shared instrument (defaults to the directory name)')
+  .option('-f, --fullscreen', 'share a read-only fullscreen preview rather than the editor')
+  .option('-b, --base-url <url>', 'the playground origin to link to', parseBaseURL, DEFAULT_PLAYGROUND_URL)
+  .option('-o, --open', 'open the generated link in your default browser')
+  .action((target: string) => {
+    const { baseUrl, fullscreen, label, open } = program.opts<{
+      baseUrl: string;
+      fullscreen?: boolean;
+      label?: string;
+      open?: boolean;
+    }>();
+
+    const files = readInstrumentFiles(target);
+    if (files.length === 0) {
+      process.stderr.write(chalk.red(`✘ No shareable source files found in ${target}\n`));
+      process.exitCode = 1;
+      return;
+    }
+
+    const shareURL = encodeShareURL({
+      baseURL: baseUrl,
+      files,
+      fullscreen,
+      label: label ?? path.basename(target)
+    });
+
+    // Status goes to stderr so the URL on stdout stays clean and pipeable.
+    process.stderr.write(
+      chalk.green('✓') +
+        chalk.dim(` Encoded ${files.length} file${files.length === 1 ? '' : 's'} (${shareURL.size} bytes)\n`)
+    );
+    process.stdout.write(shareURL.href + '\n');
+
+    if (open) {
+      openInBrowser(shareURL.href);
+    }
+  });
+
+program.parse();
diff --git a/packages/playground-url/src/index.ts b/packages/playground-url/src/index.ts
new file mode 100644
index 000000000..71ab04715
--- /dev/null
+++ b/packages/playground-url/src/index.ts
@@ -0,0 +1,10 @@
+export { $EditorFile, $EditorFiles } from './models.js';
+export type { EditorFile, PlaygroundInstrument } from './models.js';
+export {
+  decodeShareURL,
+  DEFAULT_PLAYGROUND_URL,
+  encodeShareURL,
+  generatePlaygroundURL,
+  isFullscreenShareURL
+} from './share-url.js';
+export type { EncodeShareURLOptions, ShareURL } from './share-url.js';
diff --git a/packages/playground-url/src/models.ts b/packages/playground-url/src/models.ts
new file mode 100644
index 000000000..08d382af9
--- /dev/null
+++ b/packages/playground-url/src/models.ts
@@ -0,0 +1,20 @@
+import { z } from 'zod/v4';
+
+/**
+ * A single source file of a playground instrument. The content must be a UTF-8
+ * string, mirroring the playground editor's own file model — binary assets
+ * (images, audio, video) cannot be represented in a share URL.
+ */
+export type EditorFile = z.infer<typeof $EditorFile>;
+export const $EditorFile = z.object({
+  content: z.string(),
+  name: z.string()
+});
+
+export const $EditorFiles = z.array($EditorFile);
+
+/** The minimal description of an instrument needed to (de)serialize a share URL. */
+export type PlaygroundInstrument = {
+  files: EditorFile[];
+  label: string;
+};
diff --git a/packages/playground-url/src/share-url.test.ts b/packages/playground-url/src/share-url.test.ts
new file mode 100644
index 000000000..8859c28fe
--- /dev/null
+++ b/packages/playground-url/src/share-url.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  decodeShareURL,
+  DEFAULT_PLAYGROUND_URL,
+  encodeShareURL,
+  generatePlaygroundURL,
+  isFullscreenShareURL
+} from './share-url.js';
+
+import type { PlaygroundInstrument } from './models.js';
+
+const instrument: PlaygroundInstrument = {
+  files: [
+    { content: 'export default {};', name: 'index.ts' },
+    { content: '{ "name": "test" }', name: 'meta.json' }
+  ],
+  label: 'My Instrument'
+};
+
+describe('encodeShareURL', () => {
+  it('encodes against the hosted playground by default', () => {
+    const url = encodeShareURL(instrument);
+    expect(url.origin).toBe(DEFAULT_PLAYGROUND_URL);
+    expect(url.searchParams.get('files')).toBeTruthy();
+    expect(url.searchParams.get('label')).toBeTruthy();
+  });
+
+  it('honours a custom base URL', () => {
+    const url = encodeShareURL({ ...instrument, baseURL: 'http://localhost:5173' });
+    expect(url.origin).toBe('http://localhost:5173');
+  });
+
+  it('reports the encoded byte size of the href', () => {
+    const url = encodeShareURL(instrument);
+    expect(url.size).toBe(new TextEncoder().encode(url.href).length);
+  });
+
+  it('omits the fullscreen flag unless requested', () => {
+    expect(isFullscreenShareURL(encodeShareURL(instrument))).toBe(false);
+    expect(isFullscreenShareURL(encodeShareURL({ ...instrument, fullscreen: true }))).toBe(true);
+  });
+});
+
+describe('decodeShareURL', () => {
+  it('round-trips an encoded instrument', () => {
+    const decoded = decodeShareURL(encodeShareURL(instrument));
+    expect(decoded).toEqual(instrument);
+  });
+
+  it('returns null when no instrument is present', () => {
+    expect(decodeShareURL(new URL(DEFAULT_PLAYGROUND_URL))).toBeNull();
+  });
+});
+
+describe('generatePlaygroundURL', () => {
+  it('returns the href as a string', () => {
+    expect(generatePlaygroundURL(instrument)).toBe(encodeShareURL(instrument).href);
+  });
+});
diff --git a/packages/playground-url/src/share-url.ts b/packages/playground-url/src/share-url.ts
new file mode 100644
index 000000000..505a4d0ea
--- /dev/null
+++ b/packages/playground-url/src/share-url.ts
@@ -0,0 +1,73 @@
+import { compressToEncodedURIComponent, decompressFromEncodedURIComponent } from 'lz-string';
+
+import { $EditorFiles } from './models.js';
+
+import type { EditorFile, PlaygroundInstrument } from './models.js';
+
+/** The origin of the hosted Open Data Capture playground. */
+const DEFAULT_PLAYGROUND_URL = 'https://playground.opendatacapture.org';
+
+/** A {@link URL} pointing at the playground, annotated with the encoded byte size of its `href`. */
+type ShareURL = URL & { size: number };
+
+type EncodeShareURLOptions = PlaygroundInstrument & {
+  /** The origin to build the link against. Defaults to {@link DEFAULT_PLAYGROUND_URL}. */
+  baseURL?: string;
+  /** When `true`, the link opens the instrument fullscreen as a read-only preview. */
+  fullscreen?: boolean;
+};
+
+function decodeFiles(encodedFiles: string): EditorFile[] {
+  return $EditorFiles.parse(JSON.parse(decompressFromEncodedURIComponent(encodedFiles)));
+}
+
+function encodeFiles(files: EditorFile[]): string {
+  return compressToEncodedURIComponent(JSON.stringify($EditorFiles.parse(files)));
+}
+
+/**
+ * Encode an instrument's source files into a playground share URL. Anyone who
+ * opens the returned link gets a snapshot of the provided files loaded into the
+ * playground.
+ */
+function encodeShareURL({
+  baseURL = DEFAULT_PLAYGROUND_URL,
+  files,
+  fullscreen,
+  label
+}: EncodeShareURLOptions): ShareURL {
+  const url = new URL(baseURL) as ShareURL;
+  url.searchParams.append('files', encodeFiles(files));
+  url.searchParams.append('label', compressToEncodedURIComponent(label));
+  if (fullscreen) {
+    url.searchParams.append('fullscreen', '1');
+  }
+  url.size = new TextEncoder().encode(url.href).length;
+  return url;
+}
+
+/** Returns `true` if the URL requests the fullscreen, read-only preview mode. */
+function isFullscreenShareURL(url: URL): boolean {
+  return url.searchParams.get('fullscreen') === '1';
+}
+
+/** Decode an instrument from a playground share URL, or `null` if the URL carries no instrument. */
+function decodeShareURL(url: URL): null | PlaygroundInstrument {
+  const encodedFiles = url.searchParams.get('files');
+  const encodedLabel = url.searchParams.get('label');
+  if (!(encodedFiles && encodedLabel)) {
+    return null;
+  }
+  return { files: decodeFiles(encodedFiles), label: decompressFromEncodedURIComponent(encodedLabel) };
+}
+
+/**
+ * Convenience wrapper over {@link encodeShareURL} that returns the link as a
+ * string. This is the simplest way to turn an instrument into a shareable link.
+ */
+function generatePlaygroundURL(options: EncodeShareURLOptions): string {
+  return encodeShareURL(options).href;
+}
+
+export { decodeShareURL, DEFAULT_PLAYGROUND_URL, encodeShareURL, generatePlaygroundURL, isFullscreenShareURL };
+export type { EncodeShareURLOptions, ShareURL };
diff --git a/packages/playground-url/tsconfig.json b/packages/playground-url/tsconfig.json
new file mode 100644
index 000000000..7aa08f4eb
--- /dev/null
+++ b/packages/playground-url/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ESNext"]
+  },
+  "include": ["scripts/*", "src/**/*", "vitest.config.ts"]
+}
diff --git a/packages/playground-url/vitest.config.ts b/packages/playground-url/vitest.config.ts
new file mode 100644
index 000000000..3e8757e15
--- /dev/null
+++ b/packages/playground-url/vitest.config.ts
@@ -0,0 +1,13 @@
+import { defineProject, mergeConfig } from 'vitest/config';
+
+import baseConfig from '../../vitest.config';
+
+export default mergeConfig(
+  baseConfig,
+  defineProject({
+    test: {
+      name: 'playground-url',
+      root: import.meta.dirname
+    }
+  })
+);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1ac536ab4..32657c08a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -545,6 +545,9 @@ importers:
       '@opendatacapture/instrument-bundler':
         specifier: workspace:*
         version: link:../../packages/instrument-bundler
+      '@opendatacapture/playground-url':
+        specifier: workspace:*
+        version: link:../../packages/playground-url
       '@opendatacapture/react-core':
         specifier: workspace:*
         version: link:../../packages/react-core
@@ -587,9 +590,6 @@ importers:
       lucide-react:
         specifier: ^0.503.0
         version: 0.503.0(react@vendor+react@19.x)
-      lz-string:
-        specifier: ^1.5.0
-        version: 1.5.0
       monaco-editor:
         specifier: ^0.52.2
         version: 0.52.2
@@ -936,6 +936,25 @@ importers:
 
   packages/licenses: {}
 
+  packages/playground-url:
+    dependencies:
+      chalk:
+        specifier: ^5.6.2
+        version: 5.6.2
+      commander:
+        specifier: 'catalog:'
+        version: 12.1.0
+      lz-string:
+        specifier: ^1.5.0
+        version: 1.5.0
+      zod:
+        specifier: workspace:zod__3.x@*
+        version: link:../../vendor/zod@3.x
+    devDependencies:
+      esbuild:
+        specifier: 'catalog:'
+        version: 0.23.1
+
   packages/react-core:
     dependencies:
       '@douglasneuroinformatics/libjs':

From d415aacb5ef9fac444000ad890173706eaf97a83 Mon Sep 17 00:00:00 2001
From: joshunrau <contact@joshuaunrau.com>
Date: Fri, 12 Jun 2026 14:21:15 -0400
Subject: [PATCH 2/2] add runtime v1 as dependency of outreach

---
 apps/outreach/package.json | 1 +
 pnpm-lock.yaml             | 3 +++
 2 files changed, 4 insertions(+)

diff --git a/apps/outreach/package.json b/apps/outreach/package.json
index 4eb6371a1..2e45bad0a 100644
--- a/apps/outreach/package.json
+++ b/apps/outreach/package.json
@@ -13,6 +13,7 @@
   "dependencies": {
     "@douglasneuroinformatics/libui": "catalog:",
     "@opendatacapture/licenses": "workspace:*",
+    "@opendatacapture/runtime-v1": "workspace:*",
     "@opendatacapture/schemas": "workspace:*",
     "clsx": "^2.1.1",
     "lodash-es": "workspace:lodash-es__4.x@*",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 32657c08a..4eb91979a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -460,6 +460,9 @@ importers:
       '@opendatacapture/licenses':
         specifier: workspace:*
         version: link:../../packages/licenses
+      '@opendatacapture/runtime-v1':
+        specifier: workspace:*
+        version: link:../../runtime/v1
       '@opendatacapture/schemas':
         specifier: workspace:*
         version: link:../../packages/schemas