querysub 0.176.0 → 0.178.0

package/index.d.ts

@@ -0,0 +1,15 @@
+/// <reference path="./node_modules/socket-function/index.d.ts" />
+
+export { };
+
+declare global {
+    interface SerializedModule {
+        originalSource?: string;
+    }
+    namespace NodeJS {
+        interface Module {
+            /** Needed if you are using extractType. */
+            sendFullSource?: boolean;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "querysub",
-  "version": "0.176.0",
+  "version": "0.178.0",
   "main": "index.js",
   "license": "MIT",
   "note1": "note on node-forge fork, see https://github.com/digitalbazaar/forge/issues/744 for details",
@@ -24,7 +24,7 @@
     "node-forge": "https://github.com/sliftist/forge#e618181b469b07bdc70b968b0391beb8ef5fecd6",
     "pako": "^2.1.0",
     "preact": "^10.11.3",
-    "socket-function": "^0.122.0",
+    "socket-function": "^0.124.0",
     "terser": "^5.31.0",
     "typesafecss": "^0.15.0",
     "yaml": "^2.5.0",

package/src/4-dom/qreact.tsx

@@ -96,6 +96,9 @@ export namespace qreact {
         export type Element = preact.JSX.Element;
         export type HTMLAttributes<T extends EventTarget = EventTarget> = preact.JSX.HTMLAttributes<T>;
     }
+    export namespace JSXInternal {
+        export type TargetedInputEvent<T extends EventTarget = EventTarget> = preact.JSX.TargetedInputEvent<T>;
+    }
 }
 
 
@@ -911,7 +914,7 @@ class QRenderClass {
                 }
 
                 function insertInAnchor(anchor: Anchor, node: DOMNode) {
-                    let prev = document.activeElement;
+                    //let prevFocused = document.activeElement;
                     if (!anchor) {
                         nextRootDOMNodes.push(node);
                         return;
@@ -958,9 +961,9 @@ class QRenderClass {
                     }
 
                     anchor.prev.after(node);
-                    if (prev !== document.activeElement) {
-                        debugger;
-                    }
+                    // if (prevFocused !== document.activeElement) {
+                    //     debugger;
+                    // }
                 }
 
                 let isParentSVG = !!atomic(self.data().isParentSVG);
@@ -1859,9 +1862,11 @@ function updateDOMNodeFields(domNode: DOMNode, vNode: VirtualDOM, prevVNode: Vir
             updateField(key);
         }
     } else {
-        // NOTE: I'm not sure if updating textContent is better or worse than creating a new Text node?
-        // As in, should we use `prevNode.replaceWith(document.createTextNode(result))`?
+        // NOTE: By setting textContent we don't create a new Text node. This helps
+        //  contentEditable usages distinguish between our internal nodes, and ones
+        //  generated by contentEditable.
         (domNode as any as Text).textContent = String(vNode);
+        //domNode.replaceWith(document.createTextNode(String(vNode)));
     }
 }
 

package/src/4-querysub/Querysub.ts

@@ -10,7 +10,7 @@ import { isNode, isNodeTrue, timeInMinute } from "socket-function/src/misc";
 
 import { SocketFunction } from "socket-function/SocketFunction";
 import { isHotReloading, watchFilesAndTriggerHotReloading } from "socket-function/hot/HotReloadController";
-import { RequireController, SerializedModule, setRequireBootRequire } from "socket-function/require/RequireController";
+import { RequireController, setRequireBootRequire } from "socket-function/require/RequireController";
 import { cache, cacheLimited, lazy } from "socket-function/src/caching";
 import { getOwnMachineId, getThreadKeyCert, verifyMachineIdForPublicKey } from "../-a-auth/certs";
 import { getSNICerts, publishMachineARecords } from "../-e-certs/EdgeCertController";
@@ -390,8 +390,9 @@ export class Querysub {
 
     public static afterAllRendersFinished(callback: () => void) {
         // onCommitFinished prevents duplicates, as well as only running when we are actually done
-        Querysub.onCommitFinished(() => {
-            void clientWatcher.waitForTriggerFinished()?.finally(callback);
+        Querysub.onCommitFinished(async () => {
+            await clientWatcher.waitForTriggerFinished();
+            callback();
         });
     }
 
@@ -599,6 +600,20 @@ export class Querysub {
 
         await this.addSourceMapCheck(config);
 
+        const fs = await import("fs");
+
+        RequireController.addMapGetModules(async (result, args) => {
+            await Promise.all(Object.values(result.modules).map(async (mod) => {
+                if (!require.cache[mod.filename]?.sendFullSource) return;
+                // NOTE: This is used for extractType... which is very useful. And... giving the source
+                //  isn't that big of a deal anyways...
+                try {
+                    mod.originalSource = await fs.promises.readFile(mod.filename, "utf8");
+                } catch { }
+            }));
+            return result;
+        });
+
         SocketFunction.expose(RequireController);
         setRequireBootRequire(config.rootPath);
 

package/src/functional/UndoWatch.tsx

@@ -16,6 +16,15 @@ let cborxInstance = new cborx.Encoder({ structuredClone: true });
 
 const MAX_UNDO_STACK = 200;
 
+/** Can only data created with t.undoRegion, as in:
+ values2: t.undoRegion(key => key === getUserId()).lookup(
+    {
+        key: t.string,
+        value: t.string("version10"),
+        neverSet: t.stringOptional,
+    }
+),
+ */
 export class UndoWatch extends qreact.Component<{
     // Tracks changes to this data, and undoes it when ctrl+z is pressed
     //  - Depends on undo regions being defined in the schema, via t.undoRegion

package/src/library-components/Button.tsx

@@ -69,106 +69,109 @@ type Watcher = {
 let registeredWatches = new Set<Watcher>();
 
 if (!isNode()) {
-    let insideAnims = new Set<Watcher>();
-    let keyUpListener = new Set<() => void>();
     document.addEventListener("keyup", e => {
         for (let listener of keyUpListener) {
             listener();
         }
     });
     document.addEventListener("keydown", e => {
-        let isAmbientEvent = (
-            e.target === document.body
-            // Some elements are commonly selected, but shouldn't handling key events
-            || (e.target as HTMLElement).tagName === "BUTTON"
-            || (e.target as HTMLElement).tagName === "A"
-            || (e.target as HTMLElement).tagName === "INPUT" && (e.target as HTMLInputElement).type === "checkbox"
-            //|| (e.target as HTMLElement).tagName === "INPUT" && (e.target as HTMLInputElement).type === "number" && Number.isNaN(+e.key) && !e.key.includes("Arrow")
-            //|| ["INPUT", "TEXTAREA"].includes((e.target as HTMLElement).tagName)
-        );
-        if (e.key === "Escape") {
-            (document.activeElement as any)?.blur();
-        }
-        let keyFull = e.code;
-        if (keyFull.startsWith("Key")) {
-            keyFull = keyFull.slice("Key".length);
-        }
-        if (e.metaKey) keyFull = "meta+" + keyFull;
-        if (e.altKey) keyFull = "alt+" + keyFull;
-        if (e.shiftKey) keyFull = "shift+" + keyFull;
-        if (e.ctrlKey || e.metaKey) keyFull = "ctrl+" + keyFull;
-        if (!isAmbientEvent) {
-            trigger("global+" + keyFull);
-        } else {
-            trigger("global+" + keyFull);
-            trigger(keyFull);
-        }
+        triggerKeyDown(e, false);
+    });
+}
+let insideAnims = new Set<Watcher>();
+let keyUpListener = new Set<() => void>();
+export function triggerKeyDown(e: KeyboardEvent, forceAmbient = true) {
+    let isAmbientEvent = (
+        e.target === document.body
+        // Some elements are commonly selected, but shouldn't handling key events
+        || (e.target as HTMLElement).tagName === "BUTTON"
+        || (e.target as HTMLElement).tagName === "A"
+        || (e.target as HTMLElement).tagName === "INPUT" && (e.target as HTMLInputElement).type === "checkbox"
+        //|| (e.target as HTMLElement).tagName === "INPUT" && (e.target as HTMLInputElement).type === "number" && Number.isNaN(+e.key) && !e.key.includes("Arrow")
+        //|| ["INPUT", "TEXTAREA"].includes((e.target as HTMLElement).tagName)
+    ) || forceAmbient;
+    if (e.key === "Escape") {
+        (document.activeElement as any)?.blur();
+    }
+    let keyFull = e.code;
+    if (keyFull.startsWith("Key")) {
+        keyFull = keyFull.slice("Key".length);
+    }
+    if (e.metaKey) keyFull = "meta+" + keyFull;
+    if (e.altKey) keyFull = "alt+" + keyFull;
+    if (e.shiftKey) keyFull = "shift+" + keyFull;
+    if (e.ctrlKey || e.metaKey) keyFull = "ctrl+" + keyFull;
+    if (!isAmbientEvent) {
+        trigger("global+" + keyFull);
+    } else {
+        trigger("global+" + keyFull);
+        trigger(keyFull);
+    }
 
-        function trigger(keyFull: string) {
-            keyFull = keyFull.toLowerCase();
-            let listeners = Array.from(registeredWatches).map(x => {
-                let props = Querysub.localRead(() => ({ ...x.props }), { allowProxyResults: true });
-                let match = props.hotkeys?.find(x => {
-                    let hotkey = x.toLowerCase();
-                    if (hotkey.endsWith("+toggle")) {
-                        hotkey = hotkey.slice(0, -"+toggle".length);
-                    }
-                    return hotkey === keyFull;
-                }) || "";
-                let hotkeyPriority = match && (
-                    props.hotkeyPriority
-                    ?? Querysub.localRead(() => qreact.getAncestorProps(ButtonHotkeyRegion, x)?.hotkeyPriority, { allowProxyResults: true })
-                    ?? Number.MIN_SAFE_INTEGER
-                ) || Number.MIN_SAFE_INTEGER;
-                return { match, listener: x, props, hotkeyPriority };
-            }).filter(x => x.match);
-            if (!listeners.length) return;
-            console.log(`Triggering hotkey ${JSON.stringify(keyFull)} for ${listeners.length} listeners`);
-            e.preventDefault();
-            e.stopPropagation();
-            let maxPriority = Array.from(listeners).reduce((a, b) => Math.max(a, b.hotkeyPriority), Number.MIN_SAFE_INTEGER);
-            listeners = listeners.filter(x => x.hotkeyPriority === maxPriority);
-            if (listeners.length === 0) return;
-            listeners = listeners.filter((x, index) => x.props.callEvenIfRedundant || index === listeners.length - 1);
-            for (let { match, listener, props } of listeners) {
-                if (insideAnims.has(listener)) continue;
-                listener.element?.click();
-                if (!keyFull.includes("global+")) {
-                    listener.element?.focus();
+    function trigger(keyFull: string) {
+        keyFull = keyFull.toLowerCase();
+        let listeners = Array.from(registeredWatches).map(x => {
+            let props = Querysub.localRead(() => ({ ...x.props }), { allowProxyResults: true });
+            let match = props.hotkeys?.find(x => {
+                let hotkey = x.toLowerCase();
+                if (hotkey.endsWith("+toggle")) {
+                    hotkey = hotkey.slice(0, -"+toggle".length);
                 }
-                if (match.includes("+toggle")) {
-                    function onKeyUp() {
-                        keyUpListener.delete(onKeyUp);
-                        listener.element?.click();
-                    }
-                    keyUpListener.add(onKeyUp);
+                return hotkey === keyFull;
+            }) || "";
+            let hotkeyPriority = match && (
+                props.hotkeyPriority
+                ?? Querysub.localRead(() => qreact.getAncestorProps(ButtonHotkeyRegion, x)?.hotkeyPriority, { allowProxyResults: true })
+                ?? Number.MIN_SAFE_INTEGER
+            ) || Number.MIN_SAFE_INTEGER;
+            return { match, listener: x, props, hotkeyPriority };
+        }).filter(x => x.match);
+        if (!listeners.length) return;
+        console.log(`Triggering hotkey ${JSON.stringify(keyFull)} for ${listeners.length} listeners`);
+        e.preventDefault();
+        e.stopPropagation();
+        let maxPriority = Array.from(listeners).reduce((a, b) => Math.max(a, b.hotkeyPriority), Number.MIN_SAFE_INTEGER);
+        listeners = listeners.filter(x => x.hotkeyPriority === maxPriority);
+        if (listeners.length === 0) return;
+        listeners = listeners.filter((x, index) => x.props.callEvenIfRedundant || index === listeners.length - 1);
+        for (let { match, listener, props } of listeners) {
+            if (insideAnims.has(listener)) continue;
+            listener.element?.click();
+            if (!keyFull.includes("global+")) {
+                listener.element?.focus();
+            }
+            if (match.includes("+toggle")) {
+                function onKeyUp() {
+                    keyUpListener.delete(onKeyUp);
+                    listener.element?.click();
                 }
-                if (Querysub.localRead(() => props.immediateRepeat)) {
-                    insideAnims.add(listener);
-                    let dead = false;
-                    function onKeyUp() {
-                        keyUpListener.delete(onKeyUp);
-                        insideAnims.delete(listener);
-                        dead = true;
-                    }
-                    keyUpListener.add(onKeyUp);
-                    let prevFrame = Date.now();
-                    function onFrame() {
-                        if (dead) {
-                            animationDuration = 0;
-                            return;
-                        }
-                        let now = Date.now();
-                        animationDuration = now - prevFrame;
-                        prevFrame = now;
-                        listener.element?.click();
-                        requestAnimationFrame(onFrame);
+                keyUpListener.add(onKeyUp);
+            }
+            if (Querysub.localRead(() => props.immediateRepeat)) {
+                insideAnims.add(listener);
+                let dead = false;
+                function onKeyUp() {
+                    keyUpListener.delete(onKeyUp);
+                    insideAnims.delete(listener);
+                    dead = true;
+                }
+                keyUpListener.add(onKeyUp);
+                let prevFrame = Date.now();
+                function onFrame() {
+                    if (dead) {
+                        animationDuration = 0;
+                        return;
                     }
+                    let now = Date.now();
+                    animationDuration = now - prevFrame;
+                    prevFrame = now;
+                    listener.element?.click();
                     requestAnimationFrame(onFrame);
                 }
+                requestAnimationFrame(onFrame);
             }
         }
-    });
+    }
 }
 
 let animationDuration = 0;

package/src/library-components/URLParam.ts

@@ -244,6 +244,9 @@ export function parseSearchString(search: string): { [key: string]: unknown } {
     let parts = search.split("&");
     let output: { [key: string]: string | undefined } = Object.create(null);
     for (let part of parts) {
+        if (part.endsWith("=")) {
+            part = part.slice(0, -1);
+        }
         let equalIndex = part.indexOf("=");
         if (equalIndex === -1) {
             output[decodeURIComponent(part)] = undefined;

package/src/misc/extractType.ts

@@ -0,0 +1,53 @@
+import * as fs from "fs";
+import { isNode } from "typesafecss";
+import debugbreak from "debugbreak";
+import { parseBraceGroupEndPos, parseParenGroupEndPos } from "./simpleParsing";
+/** Extract the body of a root type from a module.
+ *      Ex:
+ *          interface TestType {
+ *              x: number;
+ *          }
+ *          extractType(module, "TestType") === `{ x: number; }`
+ * 
+ *   IMPORTANT! You must also set: `module.sendFullSource = true`, serverside, statically on the module.
+ */
+
+export function extractType(module: NodeJS.Module, typeName: string): string {
+    // TODO: Use moduleContents?
+    //assertDefined2(module.moduleContents, "module.moduleContents not initialized?");
+    let code = module.original.originalSource || fs.readFileSync(module.filename).toString().replaceAll("\r", "");
+    // NOTE: This is a hack, but look for the first instance of typeName, followed by a space. That is probably the type we want.
+    //  (the space helps ensure it is the full symbol, and not just the text in a different symbol)
+    let typeStart = code.indexOf(typeName + "<");
+    if (typeStart < 0) {
+        typeStart = indexOfAsserted(code, typeName + " ");
+    }
+    typeStart = indexOfAsserted(code, "=", typeStart);
+    typeStart++;
+
+    function indexOfEnd(char: string) {
+        let index = code.indexOf(char, typeStart);
+        if (index < 0) return code.length;
+        return index;
+    }
+    let end = indexOfEnd(";");
+    // Skip any brace or paren groups
+    if (indexOfEnd("{") < end && indexOfEnd("{") < indexOfEnd("(")) {
+        // We have braces or parens
+        end = parseBraceGroupEndPos(code, typeStart)?.endPos || typeStart;
+        end = indexOfAsserted(code, ";", end);
+    } else if (indexOfEnd("(") < end) {
+        // We have braces or parens
+        end = parseParenGroupEndPos(code, typeStart)?.endPos || typeStart;
+        end = indexOfAsserted(code, ";", end);
+    }
+
+    console.log(code.slice(typeStart, end));
+
+    return code.slice(typeStart, end);
+}
+export function indexOfAsserted(text: string, search: string, startIndex?: number) {
+    let index = text.indexOf(search, startIndex);
+    if (index < 0) throw new Error(`Cannot find indexOf text "${search}" in "${text}", starting at index ${startIndex}`);
+    return index;
+}

package/src/misc/format2.ts

@@ -46,3 +46,27 @@ export function niceNumberStringify(valueIn: number) {
     }
     return value;
 }
+
+
+export function ellipsize(text: string, maxLength: number) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return text.slice(0, maxLength) + "...";
+}
+
+export function ellipsizeStart(text: string, maxLength: number) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return "..." + text.slice(-maxLength);
+}
+
+export function ellipsizeMiddle(text: string, maxLength: number) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    let halfs = Math.floor((maxLength - 3) / 2);
+    if (halfs < 1) halfs = 1;
+    return text.slice(0, halfs) + "..." + text.slice(-halfs);
+}

package/src/misc/simpleParsing.ts

@@ -0,0 +1,310 @@
+import { red } from "socket-function/src/formatting/logColors";
+import fs from "fs";
+import { ellipsizeStart } from "./format2";
+
+export function parseParenGroup(text: string, startPos: number): string | undefined {
+    const result = parseParenGroupEndPos(text, startPos);
+    if (!result) {
+        return undefined;
+    }
+    return text.slice(result.startPos, result.endPos);
+}
+export function parseParenGroupEndPos(text: string, startPos: number): { startPos: number; endPos: number } | undefined {
+    startPos = text.indexOf("(", startPos);
+    if (startPos < 0) {
+        console.warn(red(`Could not find opening parenthesis for paren group starting at ${startPos}, text ${JSON.stringify(ellipsizeStart(text, 100))}`));
+        return undefined;
+    }
+    let parensOpen = 1;
+    let endPos = startPos + 1;
+    let inLineComment = false;
+    let inBlockComment = false;
+    while (endPos < text.length) {
+        let char = text[endPos++];
+
+        if (inBlockComment) {
+            if (char === "*" && text[endPos] === "/") {
+                inBlockComment = false;
+                endPos++;
+            }
+            continue;
+        }
+
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+            }
+            continue;
+        }
+
+        if (char === "/" && text[endPos] === "/") {
+            inLineComment = true;
+            endPos++;
+            continue;
+        }
+
+        if (char === "/" && text[endPos] === "*") {
+            inBlockComment = true;
+            endPos++;
+            continue;
+        }
+
+        if (char === "(") {
+            parensOpen++;
+            continue;
+        }
+
+        if (char === ")") {
+            parensOpen--;
+            if (parensOpen === 0) {
+                break;
+            }
+            continue;
+        }
+    }
+    if (endPos >= text.length) {
+        console.warn(red(`Could not find closing parenthesis for paren group starting at ${startPos}, text ${JSON.stringify(ellipsizeStart(text, 100))}`));
+        return undefined;
+    }
+    return { startPos, endPos };
+}
+export function parseBraceGroup(text: string, startPos: number): string | undefined {
+    const result = parseBraceGroupEndPos(text, startPos);
+    if (!result) {
+        return undefined;
+    }
+    return text.slice(result.startPos, result.endPos);
+}
+
+export function parseBraceGroupEndPos(text: string, startPos: number): { startPos: number; endPos: number } | undefined {
+    startPos = text.indexOf("{", startPos);
+    if (startPos < 0) {
+        console.warn(red(`Could not find opening brace for brace group starting at ${startPos}, text ${JSON.stringify(ellipsizeStart(text, 100))}`));
+        return undefined;
+    }
+    let bracesOpen = 1;
+    let endPos = startPos + 1;
+    let inLineComment = false;
+    let inBlockComment = false;
+    while (endPos < text.length) {
+        let char = text[endPos++];
+
+        if (inBlockComment) {
+            if (char === "*" && text[endPos] === "/") {
+                inBlockComment = false;
+                endPos++;
+            }
+            continue;
+        }
+
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+            }
+            continue;
+        }
+
+        if (char === "/" && text[endPos] === "/") {
+            inLineComment = true;
+            endPos++;
+            continue;
+        }
+
+        if (char === "/" && text[endPos] === "*") {
+            inBlockComment = true;
+            endPos++;
+            continue;
+        }
+
+        if (char === "{") {
+            bracesOpen++;
+            continue;
+        }
+
+        if (char === "}") {
+            bracesOpen--;
+            if (bracesOpen === 0) {
+                break;
+            }
+            continue;
+        }
+    }
+    if (endPos >= text.length) {
+        console.warn(red(`Could not find closing brace for brace group starting at ${startPos}, text ${JSON.stringify(ellipsizeStart(text, 100))}`));
+        return undefined;
+    }
+    return { startPos, endPos };
+}
+
+export type ArgumentRegion = {
+    type: "comment";
+    text: string;
+} | {
+    type: "param";
+    name: string;
+};
+
+export type ParserContext = {
+    text: string;
+    pos: number;
+};
+
+export function parseArgumentRegions(text: string): ArgumentRegion[] {
+    const regions: ArgumentRegion[] = [];
+    const ctx: ParserContext = { text, pos: 0 };
+
+    while (ctx.pos < ctx.text.length) {
+        skipWhitespace(ctx);
+
+        if (ctx.pos >= ctx.text.length) {
+            break;
+        }
+
+        const blockComment = parseBlockComment(ctx);
+        if (blockComment) {
+            regions.push(blockComment);
+            continue;
+        }
+
+        const lineComments = parseLineComments(ctx);
+        if (lineComments) {
+            regions.push(lineComments);
+            continue;
+        }
+
+        const parameter = parseParameter(ctx);
+        if (parameter) {
+            regions.push(parameter);
+            continue;
+        }
+
+        // Skip unknown character
+        ctx.pos++;
+    }
+
+    return regions;
+}
+
+function skipWhitespace(ctx: ParserContext) {
+    while (ctx.pos < ctx.text.length && /\s/.test(ctx.text[ctx.pos])) {
+        ctx.pos++;
+    }
+}
+
+function parseBlockComment(ctx: ParserContext): ArgumentRegion | undefined {
+    if (ctx.text[ctx.pos] !== "/" || ctx.text[ctx.pos + 1] !== "*") {
+        return undefined;
+    }
+
+    const start = ctx.pos;
+    ctx.pos += 2;
+    while (ctx.pos < ctx.text.length && !(ctx.text[ctx.pos] === "*" && ctx.text[ctx.pos + 1] === "/")) {
+        ctx.pos++;
+    }
+
+    if (ctx.pos >= ctx.text.length) {
+        return undefined;
+    }
+
+    ctx.pos += 2;
+    return {
+        type: "comment",
+        text: ctx.text.slice(start + 2, ctx.pos - 2).trim()
+    };
+}
+
+function parseLineComments(ctx: ParserContext): ArgumentRegion | undefined {
+    if (ctx.text[ctx.pos] !== "/" || ctx.text[ctx.pos + 1] !== "/") {
+        return undefined;
+    }
+
+    let commentText = "";
+    while (ctx.pos < ctx.text.length) {
+        // Find start of comment
+        while (ctx.pos < ctx.text.length && ctx.text[ctx.pos] !== "/") {
+            ctx.pos++;
+        }
+        if (ctx.pos >= ctx.text.length || ctx.text[ctx.pos + 1] !== "/") {
+            break;
+        }
+
+        // Get comment content
+        ctx.pos += 2;
+        const lineStart = ctx.pos;
+        while (ctx.pos < ctx.text.length && ctx.text[ctx.pos] !== "\n") {
+            ctx.pos++;
+        }
+        commentText += (commentText ? "\n" : "") + ctx.text.slice(lineStart, ctx.pos).trim();
+
+        // Skip newline
+        if (ctx.pos < ctx.text.length) {
+            ctx.pos++;
+        }
+
+        // Check next line - if it has content before //, break
+        let nextLinePos = ctx.pos;
+        while (nextLinePos < ctx.text.length && /\s/.test(ctx.text[nextLinePos])) {
+            nextLinePos++;
+        }
+        if (nextLinePos >= ctx.text.length || ctx.text[nextLinePos] !== "/" || ctx.text[nextLinePos + 1] !== "/") {
+            break;
+        }
+        ctx.pos = nextLinePos;
+    }
+
+    if (!commentText) {
+        return undefined;
+    }
+
+    return {
+        type: "comment",
+        text: commentText
+    };
+}
+
+export function parseParameter(ctx: ParserContext): ArgumentRegion | undefined {
+    if (!/[a-zA-Z_]/.test(ctx.text[ctx.pos])) {
+        return undefined;
+    }
+
+    const nameStart = ctx.pos;
+    while (ctx.pos < ctx.text.length && /[a-zA-Z0-9_]/.test(ctx.text[ctx.pos])) {
+        ctx.pos++;
+    }
+    const name = ctx.text.slice(nameStart, ctx.pos);
+
+    // Skip whitespace and colon
+    skipWhitespace(ctx);
+    if (ctx.pos >= ctx.text.length || ctx.text[ctx.pos] !== ":") {
+        return undefined;
+    }
+
+    ctx.pos++;
+    skipWhitespace(ctx);
+
+    // Get description until semicolon, handling nested parens
+    const descStart = ctx.pos;
+    while (ctx.pos < ctx.text.length && ctx.text[ctx.pos] !== ";") {
+        if (ctx.text[ctx.pos] === "(") {
+            const parenGroup = parseParenGroup(ctx.text, ctx.pos);
+            if (!parenGroup) {
+                break;
+            }
+            ctx.pos += parenGroup.length;
+            continue;
+        }
+        ctx.pos++;
+    }
+
+    if (ctx.pos >= ctx.text.length) {
+        return undefined;
+    }
+
+    const result = {
+        type: "param" as const,
+        name,
+        description: ctx.text.slice(descStart, ctx.pos).trim()
+    };
+    ctx.pos++; // Skip semicolon
+    return result;
+}