fix(parser): make fs import conditional for browser compatibility

- Use conditional require('fs') with try/catch for browser environments
- @include directive works in Node.js/Bun (CLI) but gracefully fails in browser
- Fix CI Puppeteer installation to use 'pnpm exec' instead of 'npx'
- Ensures parser works in both server and browser environments

Fixes website deployment failure (Module not found: Can't resolve 'fs')
Maintains full CLI functionality for all NPM users

Author: alpha912

.github/workflows/ci.yml

@@ -52,7 +52,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Install Chrome for Puppeteer
-        run: npx puppeteer browsers install chrome
+        run: cd cli && pnpm exec puppeteer browsers install chrome
 
       - name: Type check
         run: pnpm run typecheck
@@ -218,9 +218,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Install Puppeteer Chrome browser
-        run: |
-          cd cli
-          npx --yes puppeteer browsers install chrome
+        run: cd cli && pnpm exec puppeteer browsers install chrome
 
       - name: Build packages
         run: pnpm run build

parser/src/parser.ts

@@ -3,7 +3,17 @@
 // Why: Entry point for parsing OSF documents and converting them back to text
 // Related: types.ts, lexer/index.ts, block-parsers/index.ts, serializers/index.ts
 
-import { readFileSync } from 'fs';
+// Conditional fs import - only available in Node.js/Bun environments
+// eslint-disable-next-line no-unused-vars
+let readFileSync: ((path: string, encoding: string) => string) | undefined;
+try {
+  // This will work in Node.js and Bun, but throw in browsers
+  readFileSync = require('fs').readFileSync;
+} catch {
+  // Browser environment - fs not available
+  // @include directive will throw helpful error if attempted
+}
+
 import { resolve, dirname, relative, normalize } from 'path';
 import { OSFDocument, OSFBlock, DocBlock, IncludeDirective, ParseOptions } from './types';
 import { findBlocks } from './lexer';
@@ -155,6 +165,15 @@ function resolveDocumentIncludes(
 
       resolvedPaths.add(fullPath);
 
+      // Check if fs is available (Node.js/Bun environment)
+      if (!readFileSync) {
+        throw new Error(
+          `@include directive requires a Node.js or Bun environment. ` +
+            `The parser is running in a browser where file system access is not available. ` +
+            `Path attempted: ${fullPath}`
+        );
+      }
+
       const content = readFileSync(fullPath, 'utf-8');
       const included = parse(content, {
         resolveIncludes: false, // Don't auto-resolve, we'll do it manually