@spacefast/common 0.0.24 → 0.2.1

package/dist/og-template.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical geometry for the Spacefast Open Graph image exported from Figma.
+ *
+ * Renderers may use different engines, but they must consume these dimensions
+ * and positions so every first-party surface produces the same template.
+ */
+export const SPACEFAST_OG_TEMPLATE = {
+    width: 2400,
+    height: 800,
+    background: "#fcfcfa",
+    grid: {
+        size: 80,
+        stroke: "#e8e8e5",
+        strokeWidth: 2,
+    },
+    title: {
+        left: 120,
+        top: 96,
+        width: 820,
+        fontFamily: "Recoleta",
+        fontWeight: 400,
+        fontSize: 112,
+        lineHeight: 0.9,
+        letterSpacing: -4,
+    },
+    wordmark: {
+        left: 136,
+        bottom: 96,
+        width: 360,
+        height: 68,
+    },
+    globe: {
+        left: 1178,
+        top: 96,
+        width: 160,
+        height: 160,
+    },
+    pin: {
+        left: 1602,
+        top: -82,
+        width: 426,
+        height: 402,
+    },
+    people: {
+        left: 1290,
+        top: 386,
+        width: 490,
+        height: 421,
+    },
+    branch: {
+        left: 2036,
+        top: 336,
+        width: 256,
+        height: 264,
+    },
+};

package/dist/slug-policy/index.js

@@ -1,4 +1,3 @@
-import { MANAGEMENT_LABEL_PREFIX } from "../config/domains.js";
 import { INFRA_SLUG_BLOCKLIST, PRODUCT_PLATFORM_SLUG_BLOCKLIST, SUBSTRING_SLUG_BLOCKLIST, TRADEMARK_EXACT_SLUG_BLOCKLIST, } from "./blocklist.js";
 export { INFRA_SLUG_BLOCKLIST, PRODUCT_PLATFORM_SLUG_BLOCKLIST, SUBSTRING_SLUG_BLOCKLIST, TRADEMARK_EXACT_SLUG_BLOCKLIST, } from "./blocklist.js";
 export const SLUG_MIN_LENGTH = 3;
@@ -9,8 +8,8 @@ const productPlatformReservedSlugs = new Set(PRODUCT_PLATFORM_SLUG_BLOCKLIST);
 const trademarkExactReservedSlugs = new Set(TRADEMARK_EXACT_SLUG_BLOCKLIST);
 export function evaluateSlugCandidate(input, options = {}) {
     const maxLength = options.maxLength ?? TEAM_SLUG_MAX_LENGTH;
-    // Explicit user choices are rejected rather than silently reshaped. Case,
-    // surrounding whitespace, and diacritics are the only accepted canonicalization.
+    // Case, surrounding whitespace, and diacritics are the only canonicalization.
+    // Anything else is rejected rather than silently reshaped.
     const casefolded = input
         .trim()
         .normalize("NFD")
@@ -47,20 +46,15 @@ function evaluateStructuralRules(normalized, structuralCandidate, maxLength) {
     if (/^[0-9]+$/.test(normalized)) {
         return invalid("Slug cannot be all numeric.");
     }
-    if (normalized.startsWith(MANAGEMENT_LABEL_PREFIX)) {
-        return reserved(`Slug cannot start with reserved prefix ${MANAGEMENT_LABEL_PREFIX}.`);
-    }
     return { ok: true, normalized };
 }
-// A substring reservation survives numeric suffixing (`paypal-2` still
-// contains `paypal`). Suggestion generators use this structured signal to
-// abandon the base instead of exhausting every suffix.
+// A substring reservation survives numeric suffixing (`paypal-2` still contains
+// `paypal`), so suggestion generators abandon the base instead of trying suffixes.
 function matchingReservedSubstring(normalized) {
     return SUBSTRING_SLUG_BLOCKLIST.find((reservedSubstring) => normalized.includes(reservedSubstring));
 }
 export function slugPolicyFailureSurvivesSuffix(normalized) {
-    return (matchingReservedSubstring(normalized) !== undefined ||
-        normalized.startsWith(MANAGEMENT_LABEL_PREFIX));
+    return matchingReservedSubstring(normalized) !== undefined;
 }
 function evaluateReservedRules(normalized) {
     if (infraReservedSlugs.has(normalized)) {

package/dist/test-helpers/fetch-stub.js

@@ -2,6 +2,7 @@ import { errorDocsUrl, errorTitle, PROBLEM_CONTENT_TYPE } from "../contracts/err
 /** The original fetch implementation captured before a test installs a stub. */
 export const realFetch = globalThis.fetch;
 export function stubFetch(handler) {
+    // SAFETY: The wrapper accepts fetch's parameter types and always resolves to the handler's Response.
     globalThis.fetch = (async (input, init) => handler(input instanceof Request && init === undefined ? input : new Request(input, init)));
 }
 export function restoreFetch() {

package/dist/utils/browser-credential.d.ts

@@ -1,10 +1,17 @@
 /**
- * Builds a browser handoff URL around a short-lived, one-use exchange token.
- *
- * The durable credential never appears in this URL. The access origin consumes
- * the final path segment once and immediately redirects browsers to a clean
- * path-scoped session. `publicId` is used only by agent handoffs, whose clean
- * static document remains `/agent/<id>`.
+ * The opaque one-use token every browser-handoff URL ends with. Exported
+ * because the agent-handoff grammar is built on it and several entrypoints
+ * (the CLI's argv sniffer among them) need the shape without paying for the
+ * agent registry that `docs/agent-setup.ts` pulls in.
+ */
+export declare const BROWSER_HANDOFF_TOKEN_PATTERN: RegExp;
+/** Path shape of an agent-handoff link, for callers that have no expected origin. */
+export declare const AGENT_HANDOFF_PATH_PATTERN: RegExp;
+/**
+ * A browser handoff URL around a short-lived, one-use exchange token. The
+ * durable credential never appears in it: the access origin consumes the final
+ * path segment once, then redirects to a clean path-scoped session. A caller can
+ * add a non-secret `publicId` only when its protocol genuinely needs one.
  */
 export declare function createBrowserCredentialUrl(input: {
     origin: string;

package/dist/utils/browser-credential.js

@@ -1,4 +1,13 @@
-const browserHandoffSegmentPattern = /^[A-Za-z0-9_-]{16,512}$/;
+/**
+ * The opaque one-use token every browser-handoff URL ends with. Exported
+ * because the agent-handoff grammar is built on it and several entrypoints
+ * (the CLI's argv sniffer among them) need the shape without paying for the
+ * agent registry that `docs/agent-setup.ts` pulls in.
+ */
+export const BROWSER_HANDOFF_TOKEN_PATTERN = /^[A-Za-z0-9_-]{16,512}$/;
+/** Path shape of an agent-handoff link, for callers that have no expected origin. */
+export const AGENT_HANDOFF_PATH_PATTERN = /^\/handoffs\/[A-Za-z0-9_-]{16,512}\/?$/;
+const browserHandoffSegmentPattern = BROWSER_HANDOFF_TOKEN_PATTERN;
 const browserHandoffPublicIdPattern = /^[A-Za-z0-9_-]{1,512}$/;
 function requireBrowserHandoffSegment(value) {
     if (!browserHandoffSegmentPattern.test(value)) {
@@ -7,12 +16,10 @@ function requireBrowserHandoffSegment(value) {
     return value;
 }
 /**
- * Builds a browser handoff URL around a short-lived, one-use exchange token.
- *
- * The durable credential never appears in this URL. The access origin consumes
- * the final path segment once and immediately redirects browsers to a clean
- * path-scoped session. `publicId` is used only by agent handoffs, whose clean
- * static document remains `/agent/<id>`.
+ * A browser handoff URL around a short-lived, one-use exchange token. The
+ * durable credential never appears in it: the access origin consumes the final
+ * path segment once, then redirects to a clean path-scoped session. A caller can
+ * add a non-secret `publicId` only when its protocol genuinely needs one.
  */
 export function createBrowserCredentialUrl(input) {
     const origin = new URL(input.origin);

package/dist/utils/build-settings.d.ts

@@ -1,3 +1,4 @@
+import { type SpaceCronConfig } from "../contracts/space-config.js";
 export type BuildSettingsInput = {
     fileNames: Iterable<string>;
     packageJson?: string | null | undefined;
@@ -24,7 +25,7 @@ export type BuildAnalyzerCandidateRankInput = {
     rootDirectory: string | null;
     fileNames: Iterable<string>;
 };
-export declare function hasWorkspaceSignal(fileNames: Iterable<string>, packageJsonText?: string | null): unknown;
+export declare function hasWorkspaceSignal(fileNames: Iterable<string>, packageJsonText?: string | null): boolean;
 export declare function rankBuildAnalyzerCandidate(input: BuildAnalyzerCandidateRankInput): {
     confidence: number;
     reasons: string[];
@@ -43,15 +44,34 @@ export type PlatformConfig = {
     redirects: Array<Record<string, unknown>>;
     rewrites: Array<Record<string, unknown>>;
     headers: Array<Record<string, unknown>>;
+    crons: Array<Record<string, unknown>>;
+    unsupportedFeatures: string[];
+};
+export type NetlifyBuildPlugin = {
+    package: string;
+    inputs: NetlifyBuildPluginInputs;
+};
+export type NetlifyBuildPluginInputValue = null | boolean | number | string | NetlifyBuildPluginInputValue[] | {
+    [name: string]: NetlifyBuildPluginInputValue;
+};
+export type NetlifyBuildPluginInputs = {
+    [name: string]: NetlifyBuildPluginInputValue;
+};
+export type NetlifyBuildConfiguration = {
+    environment: Record<string, string>;
+    plugins: NetlifyBuildPlugin[];
     unsupportedFeatures: string[];
 };
 export declare function stringField(value: Record<string, unknown> | null, key: string): string | null;
 export declare function numberField(value: Record<string, unknown> | null, key: string): number | null;
+export declare function parseNetlifyBuildConfiguration(value: string | null | undefined): NetlifyBuildConfiguration | null;
 export declare function detectPlatformConfigs(input: Omit<BuildSettingsInput, "fileNames" | "packageJson">): PlatformConfig[];
 export type PlatformRoutingConversion = {
     redirectLines: string[];
     headerBlocks: string[];
+    crons: SpaceCronConfig[];
     notes: string[];
 };
 export declare function convertPlatformRouting(configs: PlatformConfig[]): PlatformRoutingConversion;
+export declare const BUILD_MARKER_FILE_NAMES: Set<string>;
 export declare function detectBuildSettings(input: BuildSettingsInput): DetectedBuildSettings;

package/dist/utils/build-settings.js

@@ -1,5 +1,7 @@
 import { load as parseYaml } from "js-yaml";
 import { parse as parseToml } from "smol-toml";
+import { z } from "zod";
+import { SPACE_CONFIG_CAPS, spaceCronKey, spaceCronSchema, } from "../contracts/space-config.js";
 export const BUILD_ANALYZER_CANDIDATE_ROOTS = ["apps", "packages", "sites", "docs"];
 const PACKAGE_MANAGER_ONLY_FILES = new Set([
     "package.json",
@@ -12,12 +14,15 @@ const PACKAGE_MANAGER_ONLY_FILES = new Set([
     "Gemfile",
     "Gemfile.lock",
 ]);
+const WORKSPACE_ROOT_FILES = new Set([
+    "pnpm-workspace.yaml",
+    "turbo.json",
+    "nx.json",
+    "lerna.json",
+]);
 export function hasWorkspaceSignal(fileNames, packageJsonText) {
     const names = new Set(fileNames);
-    if (names.has("pnpm-workspace.yaml") ||
-        names.has("turbo.json") ||
-        names.has("nx.json") ||
-        names.has("lerna.json")) {
+    if ([...WORKSPACE_ROOT_FILES].some((file) => names.has(file))) {
         return true;
     }
     if (!packageJsonText) {
@@ -25,10 +30,14 @@ export function hasWorkspaceSignal(fileNames, packageJsonText) {
     }
     try {
         const parsed = JSON.parse(packageJsonText);
-        return (Array.isArray(parsed.workspaces) ||
-            (parsed.workspaces &&
-                typeof parsed.workspaces === "object" &&
-                Array.isArray(parsed.workspaces.packages)));
+        if (Array.isArray(parsed.workspaces)) {
+            return true;
+        }
+        if (!parsed.workspaces || typeof parsed.workspaces !== "object") {
+            return false;
+        }
+        // SAFETY: The preceding non-null object check proves workspaces can carry an optional packages property.
+        return Array.isArray(parsed.workspaces.packages);
     }
     catch {
         return false;
@@ -72,12 +81,15 @@ export function hasBuildAnalyzerCandidateSignal(input) {
         input.detected.buildCommand !== null ||
         names.has("index.html"));
 }
+const BUILD_ENVIRONMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const netlifyBuildEnvironmentValueSchema = z.union([z.string(), z.number(), z.boolean()]);
 function parseJsonObject(value) {
     if (!value) {
         return null;
     }
     try {
         const parsed = JSON.parse(value);
+        // SAFETY: The conditional establishes parsed is a non-null, non-array object before returning it as a dictionary.
         return parsed && typeof parsed === "object" && !Array.isArray(parsed)
             ? parsed
             : null;
@@ -98,6 +110,7 @@ function parseTomlObject(value) {
     }
     try {
         const parsed = parseToml(value);
+        // SAFETY: The conditional establishes parsed is a non-null, non-array object before returning it as a dictionary.
         return parsed && typeof parsed === "object" && !Array.isArray(parsed)
             ? parsed
             : null;
@@ -112,6 +125,7 @@ function parseYamlObject(value) {
     }
     try {
         const parsed = parseYaml(value);
+        // SAFETY: The conditional establishes parsed is a non-null, non-array object before returning it as a dictionary.
         return parsed && typeof parsed === "object" && !Array.isArray(parsed)
             ? parsed
             : null;
@@ -130,6 +144,7 @@ export function numberField(value, key) {
 }
 function objectField(value, key) {
     const field = value?.[key];
+    // SAFETY: The conditional establishes field is a non-null, non-array object before returning it as a dictionary.
     return field && typeof field === "object" && !Array.isArray(field)
         ? field
         : null;
@@ -140,6 +155,54 @@ function arrayField(value, key) {
         ? field.filter((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry))
         : [];
 }
+function netlifyBuildEnvironment(build) {
+    const environment = objectField(build, "environment");
+    const values = {};
+    const unsupportedFeatures = [];
+    for (const [name, value] of Object.entries(environment ?? {})) {
+        if (!BUILD_ENVIRONMENT_NAME.test(name)) {
+            unsupportedFeatures.push(`Netlify build environment variable "${name}" has an invalid name.`);
+            continue;
+        }
+        const parsed = netlifyBuildEnvironmentValueSchema.safeParse(value);
+        if (parsed.success) {
+            values[name] = String(parsed.data);
+            continue;
+        }
+        unsupportedFeatures.push(`Netlify build environment variable "${name}" must have a scalar value.`);
+    }
+    return { values, unsupportedFeatures };
+}
+function netlifyBuildPlugins(config) {
+    const plugins = [];
+    const unsupportedFeatures = [];
+    for (const entry of arrayField(config, "plugins")) {
+        const packageName = stringField(entry, "package");
+        if (!packageName) {
+            unsupportedFeatures.push("A Netlify build plugin is missing its package name.");
+            continue;
+        }
+        const inputsResult = z
+            .record(z.string(), z.json())
+            .safeParse(objectField(entry, "inputs") ?? {});
+        const inputs = inputsResult.success ? inputsResult.data : {};
+        plugins.push({ package: packageName, inputs });
+    }
+    return { plugins, unsupportedFeatures };
+}
+export function parseNetlifyBuildConfiguration(value) {
+    const config = parseTomlObject(value);
+    if (!config) {
+        return null;
+    }
+    const environment = netlifyBuildEnvironment(objectField(config, "build"));
+    const plugins = netlifyBuildPlugins(config);
+    return {
+        environment: environment.values,
+        plugins: plugins.plugins,
+        unsupportedFeatures: [...environment.unsupportedFeatures, ...plugins.unsupportedFeatures],
+    };
+}
 function vercelConfig(value) {
     const config = parseJsonObjectWithComments(value);
     if (!config) {
@@ -155,11 +218,11 @@ function vercelConfig(value) {
         redirects: arrayField(config, "redirects"),
         rewrites: arrayField(config, "rewrites"),
         headers: arrayField(config, "headers"),
+        crons: arrayField(config, "crons"),
         unsupportedFeatures: [
             ...("functions" in config ? ["Vercel functions are not converted."] : []),
             ...("middleware" in config ? ["Vercel middleware is not converted."] : []),
             ...("images" in config ? ["Vercel image optimization config is not converted."] : []),
-            ...("crons" in config ? ["Vercel cron jobs are not converted."] : []),
         ],
     };
 }
@@ -169,6 +232,7 @@ function netlifyConfig(value) {
         return null;
     }
     const build = objectField(config, "build");
+    const nativeBuild = parseNetlifyBuildConfiguration(value);
     return {
         platform: "netlify",
         rootDirectory: stringField(build, "base") ?? stringField(config, "base"),
@@ -179,10 +243,13 @@ function netlifyConfig(value) {
         redirects: arrayField(config, "redirects"),
         rewrites: [],
         headers: arrayField(config, "headers"),
+        // Netlify has no scheduled-request config: its scheduled functions are
+        // declared in function code, which this importer does not read.
+        crons: [],
         unsupportedFeatures: [
             ...("functions" in config ? ["Netlify functions are not converted."] : []),
             ...("edge_functions" in config ? ["Netlify edge functions are not converted."] : []),
-            ...("plugins" in config ? ["Netlify build plugins are not converted."] : []),
+            ...(nativeBuild?.unsupportedFeatures ?? []),
             ...("processing" in config ? ["Netlify post-processing config is not converted."] : []),
         ],
     };
@@ -224,6 +291,7 @@ function cloudflarePagesConfig(input) {
         redirects: [],
         rewrites: [],
         headers: [],
+        crons: [],
         unsupportedFeatures,
     };
 }
@@ -276,7 +344,7 @@ function vercelDestination(destination, splat) {
         converted = converted.replaceAll("$1", ":splat");
     }
     else if (splat) {
-        // `:name`, `:name*`, or `:name+` — but not a longer name sharing the prefix.
+        // `:name`, `:name*`, or `:name+`, but not a longer name sharing the prefix.
         const reference = new RegExp(`\\${splat}[*+]?(?![A-Za-z0-9_])`, "g");
         converted = converted.replace(reference, ":splat");
     }
@@ -387,6 +455,7 @@ function convertVercelHeaderRule(rule, out) {
     const entries = rule.headers;
     const headers = (Array.isArray(entries) ? entries : [])
         .map((entry) => {
+        // SAFETY: The conditional establishes entry is a non-null object before reading dictionary properties.
         const header = entry && typeof entry === "object" ? entry : null;
         const key = stringField(header, "key");
         const value = header && typeof header.value === "string" ? header.value : null;
@@ -425,8 +494,43 @@ function convertNetlifyHeaderRule(rule, out) {
     }
     out.headerBlocks.push(headerBlock(matcher, headers));
 }
+/**
+ * One `vercel.json` cron entry into an `sf.jsonc` `crons` entry. Both sides are
+ * `{ path, schedule }`, so a valid entry converts verbatim. What this guards is
+ * the tail: Vercel accepts paths and schedules our grammar does not, and has no
+ * per-project cap. Every rejection names its entry, because a cron that
+ * silently stops existing is the migration failure nobody notices.
+ */
+function convertVercelCron(rule, out) {
+    const path = stringField(rule, "path");
+    const schedule = stringField(rule, "schedule");
+    const label = `vercel.json cron ${path ?? "(missing path)"}`;
+    if (!path || !schedule) {
+        out.notes.push(`${label}: skipped — missing path or schedule.`);
+        return;
+    }
+    const parsed = spaceCronSchema.safeParse({ path, schedule });
+    if (!parsed.success) {
+        out.notes.push(`${label}: skipped — ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return;
+    }
+    if (out.crons.some((entry) => spaceCronKey(entry.path) === spaceCronKey(path))) {
+        out.notes.push(`${label}: skipped — another cron already schedules this path.`);
+        return;
+    }
+    if (out.crons.length >= SPACE_CONFIG_CAPS.crons) {
+        out.notes.push(`${label}: skipped — at most ${SPACE_CONFIG_CAPS.crons} crons are supported.`);
+        return;
+    }
+    out.crons.push(parsed.data);
+}
 export function convertPlatformRouting(configs) {
-    const out = { redirectLines: [], headerBlocks: [], notes: [] };
+    const out = {
+        redirectLines: [],
+        headerBlocks: [],
+        crons: [],
+        notes: [],
+    };
     for (const config of configs) {
         if (config.platform === "vercel") {
             for (const rule of config.redirects) {
@@ -438,6 +542,9 @@ export function convertPlatformRouting(configs) {
             for (const rule of config.headers) {
                 convertVercelHeaderRule(rule, out);
             }
+            for (const rule of config.crons) {
+                convertVercelCron(rule, out);
+            }
         }
         if (config.platform === "netlify") {
             // Netlify expresses rewrites as 200-status redirects; both arrive in
@@ -542,9 +649,8 @@ const FRAMEWORKS = [
         defaultBuildCommand: "vinxi build",
     },
     {
-        // Qwik City starters build with the repo's `build` script (`qwik build`
-        // orchestrates the package.json build.* scripts, so there is no
-        // meaningful bare-binary default); static output lands in dist.
+        // Qwik City builds through the repo's `build` script, so there is no
+        // meaningful bare-binary default; static output lands in dist.
         preset: "qwik",
         dependency: "@builder.io/qwik-city",
         outputDirectory: "dist",
@@ -671,6 +777,18 @@ const FRAMEWORKS = [
         defaultBuildCommand: "bundle exec middleman build",
     },
 ];
+// Every file name the build analyzer keys on. An archive carrying any of them
+// is a project to build, not a website.
+export const BUILD_MARKER_FILE_NAMES = new Set([
+    ...PACKAGE_MANAGER_ONLY_FILES,
+    ...WORKSPACE_ROOT_FILES,
+    "vercel.json",
+    "netlify.toml",
+    "wrangler.toml",
+    "wrangler.json",
+    "wrangler.jsonc",
+    ...FRAMEWORKS.flatMap((framework) => framework.configFiles ?? []),
+]);
 function frameworkForPreset(frameworkPreset) {
     return FRAMEWORKS.find((framework) => framework.preset === frameworkPreset) ?? null;
 }

package/dist/utils/canonical-json.d.ts

@@ -1,10 +1,8 @@
 /**
  * Recursively key-sorted JSON, so a value round-tripped through Postgres jsonb
- * (which canonicalizes key order) digests identically to one freshly built in
- * JS. Arrays keep their original order since order is meaningful there.
+ * digests identically to one freshly built in JS. Arrays keep their order.
  *
- * Every digest that has to agree across the control plane, the CLI and the
- * capsule compiler is built on this exact spelling — change it and stored
- * hashes stop matching freshly computed ones.
+ * The control plane, the CLI and the capsule compiler all digest this exact
+ * spelling. Change it and stored hashes stop matching new ones.
  */
 export declare function canonicalJson(value: unknown): string;

package/dist/utils/canonical-json.js

@@ -1,17 +1,16 @@
 /**
  * Recursively key-sorted JSON, so a value round-tripped through Postgres jsonb
- * (which canonicalizes key order) digests identically to one freshly built in
- * JS. Arrays keep their original order since order is meaningful there.
+ * digests identically to one freshly built in JS. Arrays keep their order.
  *
- * Every digest that has to agree across the control plane, the CLI and the
- * capsule compiler is built on this exact spelling — change it and stored
- * hashes stop matching freshly computed ones.
+ * The control plane, the CLI and the capsule compiler all digest this exact
+ * spelling. Change it and stored hashes stop matching new ones.
  */
 export function canonicalJson(value) {
     if (Array.isArray(value)) {
         return `[${value.map(canonicalJson).join(",")}]`;
     }
     if (value && typeof value === "object") {
+        // SAFETY: This branch establishes value is a non-null object before enumerating its entries.
         return `{${Object.entries(value)
             .toSorted(([left], [right]) => left.localeCompare(right))
             .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)

package/dist/utils/cast-transport.d.ts

@@ -1,23 +1,11 @@
-/**
- * How a client addresses Cast over Phoenix. Both Spacefast clients — the
- * dashboard's notice subscription and the injected Collab SDK — build their
- * socket and their topics here, and nowhere else.
- */
+/** Every Spacefast client builds its Cast socket and topics here, and nowhere else. */
 /**
  * The Phoenix topic a Cast room's messages travel on.
  *
- * Phoenix routes a broadcast by the *literal* topic string. Cast broadcasts
- * anything computed outside a channel process — Space notices, REST-published
- * room events — to the topic `Cast.RoomTopic.for/2` builds, so a client that
- * encodes the room key any other way joins a real and permanently silent room.
- * Both sides therefore encode exactly once, here and in that module: the `~n`
- * table first (it survives round-tripping a key that itself contains `~` or
- * `%`), then `encodeURIComponent`.
- *
- * Proven by delivery, not by inspection: `./cast-transport.test.ts` pins the
- * strings, and on the other side `room_channel_notice_test.exs` and
- * `spacefast_inbox_fanout_test.exs` join those literal topics and assert a real
- * Cast broadcast arrives on them.
+ * Phoenix routes a broadcast by the *literal* topic string, so a client that
+ * encodes the room key differently from `Cast.RoomTopic.for/2` joins a real and
+ * permanently silent room. Both sides encode once: the `~n` table first, then
+ * `encodeURIComponent`.
  */
 export declare function castRoomTopic(resourceKey: string, roomKey: string): string;
 /**

package/dist/utils/cast-transport.js

@@ -1,12 +1,7 @@
-/**
- * How a client addresses Cast over Phoenix. Both Spacefast clients — the
- * dashboard's notice subscription and the injected Collab SDK — build their
- * socket and their topics here, and nowhere else.
- */
+/** Every Spacefast client builds its Cast socket and topics here, and nowhere else. */
 /**
  * `~n` escapes, the inverse of `CastWeb.ApiContext.decode_path_segment/1`.
- * `~` goes first in intent: the map is applied in one pass, so an already
- * escaped marker can never be escaped twice.
+ * Applied in one pass with `~` first, so an escaped marker is never escaped twice.
  */
 const ESCAPED = new Map([
     ["~", "~0"],
@@ -19,18 +14,10 @@ const ESCAPED = new Map([
 /**
  * The Phoenix topic a Cast room's messages travel on.
  *
- * Phoenix routes a broadcast by the *literal* topic string. Cast broadcasts
- * anything computed outside a channel process — Space notices, REST-published
- * room events — to the topic `Cast.RoomTopic.for/2` builds, so a client that
- * encodes the room key any other way joins a real and permanently silent room.
- * Both sides therefore encode exactly once, here and in that module: the `~n`
- * table first (it survives round-tripping a key that itself contains `~` or
- * `%`), then `encodeURIComponent`.
- *
- * Proven by delivery, not by inspection: `./cast-transport.test.ts` pins the
- * strings, and on the other side `room_channel_notice_test.exs` and
- * `spacefast_inbox_fanout_test.exs` join those literal topics and assert a real
- * Cast broadcast arrives on them.
+ * Phoenix routes a broadcast by the *literal* topic string, so a client that
+ * encodes the room key differently from `Cast.RoomTopic.for/2` joins a real and
+ * permanently silent room. Both sides encode once: the `~n` table first, then
+ * `encodeURIComponent`.
  */
 export function castRoomTopic(resourceKey, roomKey) {
     let escaped = "";

package/dist/utils/claim-token.js

@@ -1,6 +1,5 @@
 // The space key (`sfc_…`, or the legacy five-word form) is the one claim
-// credential; it authenticates as a `Bearer` header and rides claim-link
-// fragments verbatim.
+// credential: it rides `Bearer` headers and claim-link fragments verbatim.
 export function normalizeClaimToken(token) {
     const trimmed = token?.trim();
     if (!trimmed) {

package/dist/utils/comment-avatars.js

@@ -21,12 +21,10 @@ export function normalizeCommentAvatarUrl(value) {
         if (source.origin === CANONICAL_GRAVATAR_ORIGIN || source.origin === AVATAR_PROXY_ORIGIN) {
             return source.href.length <= MAX_AVATAR_URL_LENGTH ? source.href : null;
         }
-        // Assign the proxy path instead of parsing `<host><path>` as a URL. A host
-        // with a non-default port contains a colon and would otherwise become a
-        // made-up scheme (`javascript:8443/...`, for example). Photon addresses an
-        // HTTPS source with `ssl=1`; without it, an HTTPS and HTTP source collapse
-        // to the same proxy URL. `source.host` deliberately retains an explicit
-        // non-default port.
+        // Assign the proxy path instead of parsing `<host><path>` as a URL: a host
+        // with a non-default port carries a colon and would become a made-up scheme
+        // (`javascript:8443/...`). `ssl=1` keeps an HTTPS and an HTTP source from
+        // collapsing to the same proxy URL.
         const proxied = new URL(AVATAR_PROXY_ORIGIN);
         proxied.pathname = `/${source.host}${source.pathname}`;
         proxied.search = source.search;

package/dist/utils/concurrency.js

@@ -10,15 +10,15 @@ export async function mapConcurrent(items, limit, mapper) {
         if (index >= items.length) {
             return;
         }
+        // SAFETY: the bounds check above proves this index addresses an item in the input array.
         results[index] = await mapper(items[index], index);
         await worker();
     }
     await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
     return results;
 }
-// Runs predicates in bounded batches while preserving Array.find semantics:
-// the earliest matching item wins, and only a rejection before that match is
-// observable. Later batches are never started after a match is found.
+// Bounded batches with Array.find semantics: the earliest matching item wins,
+// and only a rejection before that match is observable.
 export async function findConcurrent(items, limit, predicate) {
     if (!Number.isInteger(limit) || limit < 1) {
         throw new Error("Concurrency limit must be a positive integer.");