@portel/photon 1.29.0 → 1.31.0

package/dist/runtime/cf-local.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Local Cloudflare runtime adapter for the new `Cloudflare` injection
+ * surface. Backs `private cf: Cloudflare` constructor params (and the
+ * forgiving auto-inject path for plain classes that reference
+ * `this.cf.*`) with a miniflare sandbox when a photon runs outside a
+ * deployed Worker.
+ *
+ * Auto-naming rule (single source of truth — `bindingNameFor`):
+ *   cf.kv()        → <photon>_kv
+ *   cf.kv('x')     → <photon>_x_kv
+ *   cf.ai          → AI         (shared, single per Worker)
+ *   cf.images      → IMAGES     (shared)
+ *   cf.browser     → BROWSER    (shared)
+ *
+ * Photons no longer pick global binding names. The framework derives
+ * them from the photon name plus an optional qualifier so per-photon
+ * resources never collide.
+ *
+ * Boot is keyed off the `cf-usage-scanner` output: every literal
+ * qualifier the photon uses is configured in miniflare up front, so
+ * the first call to a binding doesn't pay a reconfigure cost. Dynamic
+ * qualifiers (`cf.kv(this.tenantId)`) only get the default binding
+ * unless the author lists overrides in `protected cfBindings`.
+ *
+ * Storage persists under `<baseDir>/.data/cf-sandbox/<photon>/` so
+ * state survives process restarts and matches the Phase A2 layout.
+ */
+import { type Cloudflare, type ScopedBindingCategory, type R2BucketLike, type KVNamespaceLike, type D1DatabaseLike, type QueueLike, type VectorizeIndexLike, type AiLike, type ImagesBindingLike, type FetcherLike } from '@portel/photon-core';
+import { type CfUsage } from '../cf-usage-scanner.js';
+/**
+ * Optional override layer. Most photons leave this empty — the
+ * auto-naming convention covers the common case. Authors set it when
+ * they need a binding to point at a pre-existing CF resource owned
+ * outside the photon (typically only matters at deploy time, not for
+ * the local sandbox).
+ *
+ * Schema mirrors the deploy-side override JSON (~/.photon/state/...).
+ * For local boot, we accept the same shape so a single
+ * `protected cfBindings` block round-trips through both layers.
+ */
+export interface CfOverrides {
+    /** Per-qualifier override of the resource name a binding points at. */
+    kv?: Record<string, string>;
+    r2?: Record<string, string>;
+    d1?: Record<string, string | {
+        name: string;
+        id: string;
+    }>;
+    queue?: Record<string, string>;
+    vectorize?: Record<string, string>;
+}
+export interface CFLocalRuntimeOptions {
+    photonName: string;
+    baseDir: string;
+    /**
+     * Static-analysis output from cf-usage-scanner. Determines which
+     * binding names miniflare boots with. When absent, only the
+     * default per-category binding is configured (callers that hit a
+     * qualified binding without source-scanning will get a clear miss
+     * error from miniflare).
+     */
+    usage?: CfUsage;
+    /** Optional `protected cfBindings` override layer, see CfOverrides. */
+    overrides?: CfOverrides;
+}
+/**
+ * Legacy override schema. The Phase A2 release shipped `cfBindings`
+ * as a `Record<bindingName, resourceId>` declaration that doubled as
+ * a binding declaration. Under the new auto-naming model
+ * (bindingNameFor) the same shape becomes a pure override layer —
+ * authors who want to repoint a default binding at a pre-existing
+ * resource still write the same JSON. Kept exported so deploy code
+ * and the photon-cf CLI keep building during the migration.
+ */
+export type CfBindingsConfig = CfOverrides & {
+    ai?: boolean;
+    images?: boolean;
+    browser?: boolean;
+};
+/**
+ * Merge two CfBindingsConfig blobs. Used by the deploy pipeline to
+ * stack a per-photon override JSON on top of in-source declarations.
+ * Boolean shared flags are last-write-wins; per-binding records merge
+ * key-by-key.
+ */
+export declare function mergeBindings(base: CfBindingsConfig | null | undefined, override: CfBindingsConfig | null | undefined): CfBindingsConfig;
+export declare class CFLocalRuntime implements Cloudflare {
+    private mfPromise;
+    private readonly photonName;
+    private readonly baseDir;
+    private readonly usage;
+    private readonly overrides;
+    /**
+     * Legacy mode means the photon was constructed via the Phase-A2
+     * positional `(name, cfBindings, baseDir)` form. In that mode the
+     * `qualifier` arg passed to `cf.kv(...)` etc. is treated as a
+     * literal binding name (not run through `bindingNameFor`), and
+     * miniflare seeds the names declared in `overrides.<category>`.
+     * The new options-form constructor flips this to false and the
+     * auto-naming convention takes over.
+     */
+    private readonly legacyMode;
+    private readonly legacyBooleanFlags;
+    /**
+     * New options-object form (preferred). Hosts that source-scan the
+     * photon for `Cloudflare` usage pass the scanner output as `usage`
+     * so miniflare seeds every literal-qualified binding upfront.
+     */
+    constructor(opts: CFLocalRuntimeOptions);
+    /**
+     * Legacy positional form retained for the classic loader and
+     * existing CF-runtime tests. Translates the Phase-A2 `cfBindings`
+     * declaration to the new override schema; auto-naming is disabled
+     * (no usage scan) so explicit binding names take precedence over
+     * `<photon>_<category>` defaults. Callers should migrate to the
+     * options form when the demolition commit lands.
+     *
+     * @deprecated use the options-object constructor.
+     */
+    constructor(photonName: string, bindings: CfBindingsConfig, baseDir: string);
+    /** Legacy alias retained for callers that built against the Phase-A2 API. */
+    getBindings(): CfBindingsConfig;
+    /** Inspector for tools/CLI: lists every binding miniflare seeded. */
+    getSeededBindings(): Record<ScopedBindingCategory, string[]>;
+    /**
+     * Resolve the miniflare binding name for a `cf.<cat>(qualifier?)`
+     * call. In auto-naming mode runs through `bindingNameFor`; in
+     * legacy mode treats the arg as a literal binding name (matching
+     * the Phase-A2 `cf.kv(name)` semantics).
+     */
+    private resolveBindingName;
+    dispose(): Promise<void>;
+    kv(qualifier?: string): KVNamespaceLike;
+    r2(qualifier?: string): R2BucketLike;
+    d1(qualifier?: string): D1DatabaseLike;
+    queue<Body = unknown>(qualifier?: string): QueueLike<Body>;
+    vectorize(qualifier?: string): VectorizeIndexLike;
+    get ai(): AiLike;
+    get images(): ImagesBindingLike;
+    get browser(): FetcherLike;
+    fetch(_input: string, _init?: unknown): Promise<unknown>;
+    /** Lazily boot a Miniflare instance scoped to this photon. */
+    private getMiniflare;
+    /**
+     * Build a thin proxy whose methods defer to a binding fetched via
+     * `mf.getKVNamespace(name)` / `mf.getR2Bucket(name)` / etc on first
+     * invocation. Avoids paying the boot cost on cold paths.
+     */
+    private scopedBinding;
+    /**
+     * Pull a binding off the miniflare-built env (for AI, Vectorize,
+     * Images — categories that surface as env props rather than via a
+     * dedicated `mf.getXxx(name)` accessor).
+     */
+    private envBindingProxy;
+}
+//# sourceMappingURL=cf-local.d.ts.map

package/dist/runtime/cf-local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-local.d.ts","sourceRoot":"","sources":["../../src/runtime/cf-local.ts"],"names":[],"mappings":"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"}

package/dist/runtime/cf-local.js

@@ -0,0 +1,406 @@
+/**
+ * Local Cloudflare runtime adapter for the new `Cloudflare` injection
+ * surface. Backs `private cf: Cloudflare` constructor params (and the
+ * forgiving auto-inject path for plain classes that reference
+ * `this.cf.*`) with a miniflare sandbox when a photon runs outside a
+ * deployed Worker.
+ *
+ * Auto-naming rule (single source of truth — `bindingNameFor`):
+ *   cf.kv()        → <photon>_kv
+ *   cf.kv('x')     → <photon>_x_kv
+ *   cf.ai          → AI         (shared, single per Worker)
+ *   cf.images      → IMAGES     (shared)
+ *   cf.browser     → BROWSER    (shared)
+ *
+ * Photons no longer pick global binding names. The framework derives
+ * them from the photon name plus an optional qualifier so per-photon
+ * resources never collide.
+ *
+ * Boot is keyed off the `cf-usage-scanner` output: every literal
+ * qualifier the photon uses is configured in miniflare up front, so
+ * the first call to a binding doesn't pay a reconfigure cost. Dynamic
+ * qualifiers (`cf.kv(this.tenantId)`) only get the default binding
+ * unless the author lists overrides in `protected cfBindings`.
+ *
+ * Storage persists under `<baseDir>/.data/cf-sandbox/<photon>/` so
+ * state survives process restarts and matches the Phase A2 layout.
+ */
+import * as path from 'path';
+import { bindingNameFor, } from '@portel/photon-core';
+import { expandScopedBindingNames } from '../cf-usage-scanner.js';
+/**
+ * Merge two CfBindingsConfig blobs. Used by the deploy pipeline to
+ * stack a per-photon override JSON on top of in-source declarations.
+ * Boolean shared flags are last-write-wins; per-binding records merge
+ * key-by-key.
+ */
+export function mergeBindings(base, override) {
+    const merged = { ...(base ?? {}) };
+    if (!override)
+        return merged;
+    for (const cat of ['kv', 'r2', 'queue', 'vectorize']) {
+        const ov = override[cat];
+        if (ov) {
+            merged[cat] = { ...(merged[cat] ?? {}), ...ov };
+        }
+    }
+    if (override.d1) {
+        merged.d1 = { ...(merged.d1 ?? {}), ...override.d1 };
+    }
+    for (const cat of ['ai', 'images', 'browser']) {
+        if (typeof override[cat] === 'boolean')
+            merged[cat] = override[cat];
+    }
+    return merged;
+}
+const SCOPED = ['kv', 'r2', 'd1', 'queue', 'vectorize'];
+const SHARED_BINDING_NAMES = {
+    ai: 'AI',
+    images: 'IMAGES',
+    browser: 'BROWSER',
+};
+export class CFLocalRuntime {
+    mfPromise = null;
+    photonName;
+    baseDir;
+    usage;
+    overrides;
+    /**
+     * Legacy mode means the photon was constructed via the Phase-A2
+     * positional `(name, cfBindings, baseDir)` form. In that mode the
+     * `qualifier` arg passed to `cf.kv(...)` etc. is treated as a
+     * literal binding name (not run through `bindingNameFor`), and
+     * miniflare seeds the names declared in `overrides.<category>`.
+     * The new options-form constructor flips this to false and the
+     * auto-naming convention takes over.
+     */
+    legacyMode;
+    legacyBooleanFlags;
+    constructor(optsOrName, legacyBindings, legacyBaseDir) {
+        if (typeof optsOrName === 'string') {
+            this.photonName = optsOrName;
+            this.baseDir = legacyBaseDir ?? '';
+            this.usage = null;
+            this.overrides = legacyBindings ?? {};
+            this.legacyMode = true;
+            this.legacyBooleanFlags = {
+                ai: legacyBindings?.ai === true,
+                images: legacyBindings?.images === true,
+                browser: legacyBindings?.browser === true,
+            };
+        }
+        else {
+            this.photonName = optsOrName.photonName;
+            this.baseDir = optsOrName.baseDir;
+            this.usage = optsOrName.usage ?? null;
+            this.overrides = optsOrName.overrides ?? {};
+            this.legacyMode = false;
+            this.legacyBooleanFlags = { ai: false, images: false, browser: false };
+        }
+    }
+    /** Legacy alias retained for callers that built against the Phase-A2 API. */
+    getBindings() {
+        return this.overrides;
+    }
+    /** Inspector for tools/CLI: lists every binding miniflare seeded. */
+    getSeededBindings() {
+        const out = {};
+        if (this.legacyMode) {
+            // Legacy: seed exactly what `cfBindings` declared, no auto-naming.
+            for (const cat of SCOPED) {
+                const declared = this.overrides[cat];
+                if (!declared) {
+                    out[cat] = [];
+                    continue;
+                }
+                out[cat] = Object.keys(declared);
+            }
+            return out;
+        }
+        if (!this.usage) {
+            for (const cat of SCOPED)
+                out[cat] = [bindingNameFor(this.photonName, cat)];
+            return out;
+        }
+        return expandScopedBindingNames(this.photonName, this.usage);
+    }
+    /**
+     * Resolve the miniflare binding name for a `cf.<cat>(qualifier?)`
+     * call. In auto-naming mode runs through `bindingNameFor`; in
+     * legacy mode treats the arg as a literal binding name (matching
+     * the Phase-A2 `cf.kv(name)` semantics).
+     */
+    resolveBindingName(category, qualifier) {
+        if (this.legacyMode) {
+            // Legacy callers pass the binding name directly. Empty / missing
+            // is invalid in this mode (the old API required a name).
+            if (!qualifier) {
+                throw new Error(`cf.${category}() in legacy mode requires the binding name as an argument ` +
+                    `(e.g. cf.${category}('cache')). Migrate to the new options-object ` +
+                    `constructor to use auto-naming.`);
+            }
+            return qualifier;
+        }
+        return bindingNameFor(this.photonName, category, qualifier);
+    }
+    async dispose() {
+        if (this.mfPromise) {
+            const mf = await this.mfPromise;
+            await mf.dispose();
+            this.mfPromise = null;
+        }
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Cloudflare interface — scoped categories with auto-naming
+    // ────────────────────────────────────────────────────────────────
+    kv(qualifier) {
+        return this.scopedBinding('kv', qualifier, ['get', 'put', 'delete', 'list']);
+    }
+    r2(qualifier) {
+        return this.scopedBinding('r2', qualifier, [
+            'head',
+            'get',
+            'put',
+            'delete',
+            'list',
+        ]);
+    }
+    d1(qualifier) {
+        const name = this.resolveBindingName('d1', qualifier);
+        const get = this.getMiniflare.bind(this);
+        return {
+            prepare: (query) => makeD1PreparedStatement(get, name, query, []),
+            batch: async (statements) => {
+                const mf = await get();
+                const db = (await mf.getD1Database(name));
+                const real = await Promise.all(statements.map(async (s) => {
+                    const candidate = s._materialize;
+                    return candidate ? candidate() : s;
+                }));
+                return db.batch(real);
+            },
+            exec: async (query) => {
+                const mf = await get();
+                const db = (await mf.getD1Database(name));
+                return db.exec(query);
+            },
+            dump: async () => {
+                const mf = await get();
+                const db = (await mf.getD1Database(name));
+                return db.dump();
+            },
+        };
+    }
+    queue(qualifier) {
+        return this.scopedBinding('queue', qualifier, ['send', 'sendBatch']);
+    }
+    vectorize(qualifier) {
+        return this.envBindingProxy(this.resolveBindingName('vectorize', qualifier), [
+            'insert',
+            'upsert',
+            'query',
+            'getByIds',
+            'deleteByIds',
+        ]);
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Cloudflare interface — shared categories (single per Worker)
+    // ────────────────────────────────────────────────────────────────
+    get ai() {
+        const enabled = this.usage?.shared.ai === true || this.legacyBooleanFlags.ai;
+        if (!enabled) {
+            return throwingShared('ai', 'reference this.cf.ai (or cf.ai) somewhere in the photon to enable');
+        }
+        return this.envBindingProxy(SHARED_BINDING_NAMES.ai, ['run']);
+    }
+    get images() {
+        const enabled = this.usage?.shared.images === true || this.legacyBooleanFlags.images;
+        if (!enabled) {
+            return throwingShared('images', 'reference this.cf.images (or cf.images) somewhere in the photon to enable');
+        }
+        return this.envBindingProxy(SHARED_BINDING_NAMES.images, [
+            'info',
+            'input',
+        ]);
+    }
+    get browser() {
+        return throwingShared('browser', 'browser rendering requires a Chromium dep and is deferred until a photon dogfoods it');
+    }
+    fetch(_input, _init) {
+        return Promise.reject(new Error('cf.fetch() — not yet supported on the local sandbox. Service-binding ' +
+            'fetch lands with the deploy adapter; until then, use plain `fetch()` ' +
+            'or wire the photon up to a deployed Worker.'));
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Internals
+    // ────────────────────────────────────────────────────────────────
+    /** Lazily boot a Miniflare instance scoped to this photon. */
+    getMiniflare() {
+        if (!this.mfPromise) {
+            this.mfPromise = (async () => {
+                const { Miniflare } = await import('miniflare');
+                const sandbox = path.join(this.baseDir, '.data', 'cf-sandbox', this.photonName);
+                const seeded = this.getSeededBindings();
+                const options = {
+                    modules: true,
+                    script: 'export default { async fetch() { return new Response("noop"); } };',
+                };
+                if (seeded.kv.length > 0) {
+                    options.kvNamespaces = seeded.kv;
+                    options.kvPersist = path.join(sandbox, 'kv');
+                }
+                if (seeded.r2.length > 0) {
+                    options.r2Buckets = seeded.r2;
+                    options.r2Persist = path.join(sandbox, 'r2');
+                }
+                if (seeded.d1.length > 0) {
+                    options.d1Databases = seeded.d1;
+                    options.d1Persist = path.join(sandbox, 'd1');
+                }
+                if (seeded.queue.length > 0) {
+                    const producers = {};
+                    for (const bindingName of seeded.queue) {
+                        // Local sandbox: queue name == binding name. Overrides only
+                        // come into play at deploy time.
+                        producers[bindingName] = { queueName: bindingName };
+                    }
+                    options.queueProducers = producers;
+                }
+                if (seeded.vectorize.length > 0) {
+                    const indices = {};
+                    for (const bindingName of seeded.vectorize) {
+                        indices[bindingName] = { indexName: bindingName };
+                    }
+                    options.vectorize = indices;
+                }
+                if (this.usage?.shared.ai) {
+                    options.ai = { binding: SHARED_BINDING_NAMES.ai };
+                }
+                if (this.usage?.shared.images) {
+                    options.images = { binding: SHARED_BINDING_NAMES.images };
+                }
+                // browser intentionally omitted — see `get browser` deferral.
+                return new Miniflare(options);
+            })();
+        }
+        return this.mfPromise;
+    }
+    /**
+     * Build a thin proxy whose methods defer to a binding fetched via
+     * `mf.getKVNamespace(name)` / `mf.getR2Bucket(name)` / etc on first
+     * invocation. Avoids paying the boot cost on cold paths.
+     */
+    scopedBinding(category, qualifier, methods) {
+        const name = this.resolveBindingName(category, qualifier);
+        const dynamicCategory = this.usage?.dynamicQualifiers.has(category);
+        const knownNames = new Set(this.getSeededBindings()[category]);
+        if (!knownNames.has(name) && !dynamicCategory) {
+            throw new Error(`cf.${category}(${qualifier ? JSON.stringify(qualifier) : ''}) on ` +
+                `${this.photonName} resolves to binding "${name}", which the runtime ` +
+                `did not seed. Either reference this binding with a literal qualifier ` +
+                `somewhere in your photon source (the boot scanner only sees literals), ` +
+                `or add a "${category}" override to \`protected cfBindings\`.`);
+        }
+        const get = this.getMiniflare.bind(this);
+        const out = {};
+        for (const method of methods) {
+            out[method] = async (...args) => {
+                const mf = await get();
+                const binding = await getMiniflareBinding(mf, category, name);
+                const fn = binding[method];
+                if (typeof fn !== 'function') {
+                    throw new Error(`Miniflare binding "${name}" has no method "${method}" (category=${category}).`);
+                }
+                return fn.apply(binding, args);
+            };
+        }
+        return out;
+    }
+    /**
+     * Pull a binding off the miniflare-built env (for AI, Vectorize,
+     * Images — categories that surface as env props rather than via a
+     * dedicated `mf.getXxx(name)` accessor).
+     */
+    envBindingProxy(bindingName, methods) {
+        const get = this.getMiniflare.bind(this);
+        const out = {};
+        for (const method of methods) {
+            out[method] = async (...args) => {
+                const mf = await get();
+                const env = await mf.getBindings();
+                const binding = env[bindingName];
+                if (!binding) {
+                    throw new Error(`Miniflare has no binding named '${bindingName}' (photon=${this.photonName}).`);
+                }
+                return binding[method].apply(binding, args);
+            };
+        }
+        return out;
+    }
+}
+async function getMiniflareBinding(mf, category, name) {
+    // Each miniflare accessor is typed for its specific binding; the
+    // `as never` cast keeps the dispatcher concise without giving up
+    // the runtime guarantee that `name` is one of the configured
+    // bindings (the dispatcher gate above ensures this).
+    switch (category) {
+        case 'kv':
+            return mf.getKVNamespace(name);
+        case 'r2':
+            return mf.getR2Bucket(name);
+        case 'd1':
+            return mf.getD1Database(name);
+        case 'queue':
+            return mf.getQueueProducer(name);
+        case 'vectorize': {
+            const env = await mf.getBindings();
+            return env[name];
+        }
+    }
+}
+function throwingShared(category, hint) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new Proxy(Object.create(null), {
+        get(_target, prop) {
+            throw new Error(`cf.${category}.${String(prop)} — ${hint}.`);
+        },
+    });
+}
+/**
+ * Build a chainable D1 prepared-statement proxy that mirrors
+ * `D1PreparedStatement.bind(...).first/all/run/raw()` semantics. We
+ * accumulate the bind list on the proxy and materialize the real
+ * statement only when a terminal method runs.
+ */
+function makeD1PreparedStatement(get, dbName, query, bound) {
+    const materialize = async () => {
+        const mf = await get();
+        const db = (await mf.getD1Database(dbName));
+        const stmt = db.prepare(query);
+        if (bound.length > 0)
+            return stmt.bind(...bound);
+        return stmt;
+    };
+    const proxy = {
+        bind: (...values) => makeD1PreparedStatement(get, dbName, query, [...bound, ...values]),
+        first: async (colName) => {
+            const real = (await materialize());
+            return real.first(colName);
+        },
+        run: async () => {
+            const real = (await materialize());
+            return real.run();
+        },
+        all: async () => {
+            const real = (await materialize());
+            return real.all();
+        },
+        raw: async () => {
+            const real = (await materialize());
+            return real.raw();
+        },
+        _materialize: materialize,
+    };
+    return proxy;
+}
+//# sourceMappingURL=cf-local.js.map

package/dist/runtime/cf-local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-local.js","sourceRoot":"","sources":["../../src/runtime/cf-local.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -126,7 +126,40 @@ export declare class PhotonServer {
     /** Write queue for serialized STDIO notifications (prevents interleaving from concurrent generators) */
     private _notifyQueue;
     /** Compatibility alias for tests that seed raw capabilities directly on PhotonServer */
-    rawClientCapabilities: WeakMap<Server, Record<string, any>>;
+    rawClientCapabilities: WeakMap<Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>, Record<string, any>>;
     /** Resource listing, reading, and asset serving */
     private resourceServer;
     /**
@@ -292,9 +325,16 @@ export declare class PhotonServer {
      */
     start(): Promise<void>;
     /**
-     * Start server with stdio transport
+     * Start server with stdio transport.
+     * @param webPort - when set, start a companion HTTP server on this port
+     *                  to serve @get/@post web routes for stateful photons.
      */
     private startStdio;
+    /**
+     * Dispatch an incoming HTTP request to the photon's @get/@post web routes.
+     * Used by the companion HTTP server that runs alongside STDIO stateful photons.
+     */
+    private handleWebRoute;
     /**
      * Start server with SSE transport (HTTP)
      */