studiograph 1.3.48-next.21 → 1.3.48-next.210

package/dist/server/yjs-text-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yjs-text-diff.js","sourceRoot":"","sources":["../../src/server/yjs-text-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,UAAU,GAAG,CAAC,CAAC;AACrB,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC;AAEvB;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAW,EAAE,KAAa,EAAE,MAAc,EAAE,MAAc;IACtF,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO;IAE/B,MAAM,GAAG,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7C,8EAA8E;IAC9E,0EAA0E;IAC1E,GAAG,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAEhC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;QACjB,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;YAC/B,IAAI,EAAE,KAAK,UAAU,EAAE,CAAC;gBACtB,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC;YACrB,CAAC;iBAAM,IAAI,EAAE,KAAK,WAAW,EAAE,CAAC;gBAC9B,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC/B,uEAAuE;YACzE,CAAC;iBAAM,IAAI,EAAE,KAAK,WAAW,EAAE,CAAC;gBAC9B,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACxB,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC,EAAE,MAAM,CAAC,CAAC;AACb,CAAC"}

package/dist/services/access-control.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Framework-free per-folder access control helpers.
+ *
+ * These functions decide what a given user can see or write in the workspace.
+ * They take `AuthUser | undefined` directly (not a Fastify request) so they
+ * can be reused across transports — HTTP (/api/*), MCP HTTP (/mcp), and
+ * MCP stdio all share the same rules.
+ *
+ * Rule summary:
+ * - `user === undefined` means "no identified user". On the **web** this is
+ *   API-key / open-mode (full access). On **MCP** the caller site rejects
+ *   unidentified requests before reaching these helpers, so every MCP tool
+ *   can assume a concrete user and `undefined` is never passed in.
+ * - A user can see a folder if they are an explicit member (folder_access row),
+ *   or if they are the workspace owner AND the folder has more than one member
+ *   (shared folders are visible to owners, solo folders stay private).
+ * - A user can write to a folder if they are a folder member (role = admin|editor),
+ *   or if they are the workspace owner on a shared folder.
+ * - A folder with `personal: true` is only visible/writable to its owner,
+ *   regardless of folder_access grants or workspace ownership. Stale grants
+ *   (from an older sharing attempt or test setup) cannot leak a user's
+ *   private notes to another account.
+ * - **Owner admin escalation**: workspace owners can lift the personal-
+ *   folder restriction by passing `{ includePrivate: true }` to these
+ *   helpers. The flag is enforced as owner-only inside the helpers — non-
+ *   owners passing it get no extra access. The owner-only CLI (`clone` /
+ *   `pull` / `push`) sends it unconditionally so the owner always sees every
+ *   folder; web / API surfaces opt in via the `?include_private=1` query
+ *   param on `/api/repos` or the `X-Studiograph-Include-Private: 1` header
+ *   for git transport. Used for migrations, audits, and offboarding.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+import type { RepoConfig } from '../core/types.js';
+import { type AuthService, type AuthUser } from './auth-service.js';
+/**
+ * Options accepted by the access helpers. `includePrivate` is an owner-
+ * gated admin escalation: workspace owners can opt into seeing every
+ * folder (including other users' personal ones) for migration / audit /
+ * offboarding work. Default operations stay scoped so the owner's daily
+ * workflow isn't cluttered with members' private content.
+ */
+export interface AccessOptions {
+    /** Owner-only override: when true AND caller is a workspace owner, the
+     *  personal-folder restriction is lifted. No-op for non-owners. */
+    includePrivate?: boolean;
+}
+/**
+ * Return the list of repos the user can access (content visibility).
+ * Unidentified caller (undefined) → full access, preserves legacy
+ * web / API-key behavior.
+ */
+export declare function getAccessibleRepos(user: AuthUser | undefined, workspaceManager: WorkspaceManager, authService: AuthService, opts?: AccessOptions): RepoConfig[];
+/** True if the user may read the given folder's contents. */
+export declare function hasRepoAccess(user: AuthUser | undefined, repoName: string, workspaceManager: WorkspaceManager, authService: AuthService, opts?: AccessOptions): boolean;
+/** True if the user is a folder admin on the given repo, OR a workspace
+ *  owner on a shared folder (>1 member). Solo/private folders require
+ *  actual folder-admin membership — workspace ownership alone does not
+ *  let owners rename, delete, or push members into a private folder. */
+export declare function isFolderAdminOrOwner(user: AuthUser | undefined, repoName: string, workspaceManager: WorkspaceManager, authService: AuthService): boolean;
+/**
+ * True if the user may write (create/update/delete entities) in the given folder.
+ * Membership grants write access regardless of role (both 'admin' and 'editor'
+ * can edit), and workspace owners can write to shared folders.
+ */
+export declare function canWriteRepo(user: AuthUser | undefined, repoName: string, workspaceManager: WorkspaceManager, authService: AuthService): boolean;
+/**
+ * Build a set of all entity IDs visible to the user across their accessible
+ * folders. Returns null when the caller is unidentified (no filtering needed —
+ * `filterWikilinks` treats null as "no-op").
+ */
+export declare function getAccessibleEntityIds(user: AuthUser | undefined, workspaceManager: WorkspaceManager, authService: AuthService): Set<string> | null;
+/** Filter a wikilink list to only entities the caller can access. */
+export declare function filterWikilinks(wikilinks: string[], accessibleIds: Set<string> | null): string[];

package/dist/services/access-control.js

@@ -0,0 +1,165 @@
+/**
+ * Framework-free per-folder access control helpers.
+ *
+ * These functions decide what a given user can see or write in the workspace.
+ * They take `AuthUser | undefined` directly (not a Fastify request) so they
+ * can be reused across transports — HTTP (/api/*), MCP HTTP (/mcp), and
+ * MCP stdio all share the same rules.
+ *
+ * Rule summary:
+ * - `user === undefined` means "no identified user". On the **web** this is
+ *   API-key / open-mode (full access). On **MCP** the caller site rejects
+ *   unidentified requests before reaching these helpers, so every MCP tool
+ *   can assume a concrete user and `undefined` is never passed in.
+ * - A user can see a folder if they are an explicit member (folder_access row),
+ *   or if they are the workspace owner AND the folder has more than one member
+ *   (shared folders are visible to owners, solo folders stay private).
+ * - A user can write to a folder if they are a folder member (role = admin|editor),
+ *   or if they are the workspace owner on a shared folder.
+ * - A folder with `personal: true` is only visible/writable to its owner,
+ *   regardless of folder_access grants or workspace ownership. Stale grants
+ *   (from an older sharing attempt or test setup) cannot leak a user's
+ *   private notes to another account.
+ * - **Owner admin escalation**: workspace owners can lift the personal-
+ *   folder restriction by passing `{ includePrivate: true }` to these
+ *   helpers. The flag is enforced as owner-only inside the helpers — non-
+ *   owners passing it get no extra access. The owner-only CLI (`clone` /
+ *   `pull` / `push`) sends it unconditionally so the owner always sees every
+ *   folder; web / API surfaces opt in via the `?include_private=1` query
+ *   param on `/api/repos` or the `X-Studiograph-Include-Private: 1` header
+ *   for git transport. Used for migrations, audits, and offboarding.
+ */
+import { isWorkspaceOwner } from './auth-service.js';
+/** True if the folder is `personal: true` and the caller is not its owner.
+ *  The personal flag is an owner-private invariant: it overrides folder_access
+ *  rows and workspace ownership. Unidentified callers (open mode / API key)
+ *  are never restricted — `undefined` user means full access. */
+function isRestrictedPersonalFolder(user, repoName, workspaceManager) {
+    if (!user)
+        return false;
+    const repo = workspaceManager.getRepoConfig(repoName);
+    if (!repo?.personal)
+        return false;
+    // Missing owner_id on a personal folder would be a config bug; err on
+    // the side of deny to avoid leaking content.
+    return repo.owner_id === undefined || repo.owner_id !== user.id;
+}
+/** True if the folder is workspace-wide (the reserved shared asset store).
+ *  Every authenticated member gets read + write (upload) without a
+ *  folder_access grant. This does NOT grant folder-admin (rename/delete the
+ *  folder) or per-asset deletion — those stay owner/uploader-scoped. A
+ *  workspace-wide folder must never also be `personal`. */
+function isWorkspaceWide(repoName, workspaceManager) {
+    return workspaceManager.getRepoConfig(repoName)?.workspace_wide === true;
+}
+/**
+ * Return the list of repos the user can access (content visibility).
+ * Unidentified caller (undefined) → full access, preserves legacy
+ * web / API-key behavior.
+ */
+export function getAccessibleRepos(user, workspaceManager, authService, opts = {}) {
+    const allRepos = workspaceManager.getAllRepoConfigs();
+    if (!user)
+        return allRepos;
+    const allowed = new Set(authService.getUserFolders(user.id));
+    const isOwner = isWorkspaceOwner(user.role);
+    const ownerOverride = isOwner && opts.includePrivate === true;
+    return allRepos.filter(r => {
+        if (ownerOverride)
+            return true;
+        // Personal folders are owner-only, regardless of grants.
+        if (r.personal && r.owner_id !== user.id)
+            return false;
+        // Workspace-wide folders (the shared asset store) are visible to every
+        // member without a grant. (Mutually exclusive with `personal`.)
+        if (r.workspace_wide)
+            return true;
+        if (allowed.has(r.name))
+            return true;
+        if (isOwner && authService.getFolderMembers(r.name).length > 1)
+            return true;
+        return false;
+    });
+}
+/** True if the user may read the given folder's contents. */
+export function hasRepoAccess(user, repoName, workspaceManager, authService, opts = {}) {
+    if (!user)
+        return true;
+    const isOwner = isWorkspaceOwner(user.role);
+    if (isOwner && opts.includePrivate === true)
+        return true;
+    if (isRestrictedPersonalFolder(user, repoName, workspaceManager))
+        return false;
+    if (isWorkspaceWide(repoName, workspaceManager))
+        return true;
+    if (authService.getUserFolders(user.id).includes(repoName))
+        return true;
+    if (isOwner && authService.getFolderMembers(repoName).length > 1)
+        return true;
+    return false;
+}
+/** True if the user is a folder admin on the given repo, OR a workspace
+ *  owner on a shared folder (>1 member). Solo/private folders require
+ *  actual folder-admin membership — workspace ownership alone does not
+ *  let owners rename, delete, or push members into a private folder. */
+export function isFolderAdminOrOwner(user, repoName, workspaceManager, authService) {
+    if (!user)
+        return true;
+    if (isRestrictedPersonalFolder(user, repoName, workspaceManager))
+        return false;
+    if (authService.isFolderAdmin(user.id, repoName))
+        return true;
+    if (isWorkspaceOwner(user.role) && authService.getFolderMembers(repoName).length > 1)
+        return true;
+    return false;
+}
+/**
+ * True if the user may write (create/update/delete entities) in the given folder.
+ * Membership grants write access regardless of role (both 'admin' and 'editor'
+ * can edit), and workspace owners can write to shared folders.
+ */
+export function canWriteRepo(user, repoName, workspaceManager, authService) {
+    if (!user)
+        return true;
+    if (isRestrictedPersonalFolder(user, repoName, workspaceManager))
+        return false;
+    // Workspace-wide store: any member may upload (create/update). Per-asset
+    // DELETE is restricted separately at the asset-delete route (uploader +
+    // workspace owner) — write access here does not imply delete-anyone's-asset.
+    if (isWorkspaceWide(repoName, workspaceManager))
+        return true;
+    const role = authService.getFolderRole(user.id, repoName);
+    if (role === 'admin' || role === 'editor')
+        return true;
+    if (isWorkspaceOwner(user.role) && authService.getFolderMembers(repoName).length > 1)
+        return true;
+    return false;
+}
+/**
+ * Build a set of all entity IDs visible to the user across their accessible
+ * folders. Returns null when the caller is unidentified (no filtering needed —
+ * `filterWikilinks` treats null as "no-op").
+ */
+export function getAccessibleEntityIds(user, workspaceManager, authService) {
+    if (!user)
+        return null;
+    const repos = getAccessibleRepos(user, workspaceManager, authService);
+    const ids = new Set();
+    for (const repo of repos) {
+        try {
+            const graph = workspaceManager.getGraph(repo.name);
+            for (const e of graph.search({})) {
+                ids.add(e.id);
+            }
+        }
+        catch { /* skip unmounted repos */ }
+    }
+    return ids;
+}
+/** Filter a wikilink list to only entities the caller can access. */
+export function filterWikilinks(wikilinks, accessibleIds) {
+    if (!accessibleIds)
+        return wikilinks;
+    return wikilinks.filter(id => accessibleIds.has(id));
+}
+//# sourceMappingURL=access-control.js.map

package/dist/services/access-control.js.map

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

package/dist/services/artifact-asset-token.d.ts

@@ -0,0 +1,69 @@
+/**
+ * HMAC-signed capability token that lets a SANDBOXED artifact iframe load the
+ * workspace images it embeds.
+ *
+ * Why this exists: artifact iframes run with `sandbox="allow-scripts"` (no
+ * `allow-same-origin`) → opaque origin → the `__sg_token` session cookie is
+ * NOT sent on `<img>`/CSS asset requests, and an `<img>` can't carry a Bearer
+ * header. So authorized image loads need the credential IN THE URL (`?at=`).
+ *
+ * Security shape (see ~/.claude/plans/artifact-asset-proxy.md):
+ *  - **Artifact-scoped allowlist** — the token names the EXACT `assetId/filename`
+ *    keys the artifact references (`assets`), not the whole repo. Malicious
+ *    artifact JS holding the token can only re-load the images already on the
+ *    page, not enumerate the repo.
+ *  - **Bound user** — `userId` is re-checked at serve time (`hasRepoAccess`), so
+ *    a token stops working the moment the user loses access (modulo browser
+ *    cache; the serve path uses revalidate+ETag, not immutable).
+ *  - **Purpose-pinned** — verify REJECTS any JWT that isn't `purpose:
+ *    'artifact-asset'`, so a session/OAuth JWT signed with the same secret can
+ *    never satisfy this gate (and this token can never satisfy a session gate).
+ *
+ * Signed with the workspace JWT secret via `authService.getJwtSecret()` — one
+ * rotation lever, same as `asset-upload-token.ts`.
+ *
+ * The token is a bearer credential visible to (untrusted) artifact JS. The
+ * defenses above (narrow asset allowlist + serve-time access re-check + short
+ * TTL) — NOT `connect-src 'none'` — are what make that acceptable: artifact JS
+ * can `postMessage` the token out, but it only unlocks this artifact's own
+ * images for a user who still has access.
+ */
+/** Thrown by `verifyArtifactAssetToken` on tamper / expiry / wrong secret /
+ *  wrong purpose / malformed shape. Callers map it to a fail-closed 404. */
+export declare class ArtifactAssetTokenError extends Error {
+    readonly code = "artifact_asset_token_invalid";
+    constructor(message: string);
+}
+export interface ArtifactAssetTokenPayload {
+    /** Discriminator. Verify rejects any token without exactly this value, which
+     *  is what keeps session/OAuth JWTs (signed with the same secret) out. */
+    purpose: 'artifact-asset';
+    /** The repo the artifact lives in. Serve re-checks `payload.repo === row.repo`. */
+    repo: string;
+    /** The artifact entity id this token was minted for (audit + scoping context). */
+    artifactId: string;
+    /** Allowlist of exact `${assetId}/${filename}` keys the artifact references.
+     *  Serve refuses any key not in this set — the token can't read sibling or
+     *  unrelated assets even within the same repo. */
+    assets: string[];
+    /** Auth user id (as string) the token was minted for. Re-resolved + re-authed
+     *  at serve time so revocation/removal takes effect before expiry. */
+    userId: string;
+}
+export declare const ARTIFACT_ASSET_TOKEN_TTL_SECONDS: number;
+export declare function signArtifactAssetToken(payload: ArtifactAssetTokenPayload, secret: string): string;
+/**
+ * Verify a token and return its payload. Throws `ArtifactAssetTokenError` on:
+ *   - tamper (any field mutated) / wrong secret (rotation) / expired / malformed
+ *   - wrong or missing `purpose` (rejects session + OAuth JWTs decisively)
+ *
+ * The caller (asset route, token path) is responsible for the post-verify
+ * checks the signature alone can't make:
+ *   - `payload.repo === row.repo`
+ *   - `${row.assetId}/${row.filename}` ∈ `payload.assets`
+ *   - re-resolve `payload.userId` and re-run `hasRepoAccess`
+ */
+export declare function verifyArtifactAssetToken(token: string, secret: string): ArtifactAssetTokenPayload;
+/** Build the canonical allowlist key for an asset. Centralized so the mint,
+ *  serve, and tests can't drift on separator/whitespace. */
+export declare function artifactAssetKey(assetId: string, filename: string): string;

package/dist/services/artifact-asset-token.js

@@ -0,0 +1,94 @@
+/**
+ * HMAC-signed capability token that lets a SANDBOXED artifact iframe load the
+ * workspace images it embeds.
+ *
+ * Why this exists: artifact iframes run with `sandbox="allow-scripts"` (no
+ * `allow-same-origin`) → opaque origin → the `__sg_token` session cookie is
+ * NOT sent on `<img>`/CSS asset requests, and an `<img>` can't carry a Bearer
+ * header. So authorized image loads need the credential IN THE URL (`?at=`).
+ *
+ * Security shape (see ~/.claude/plans/artifact-asset-proxy.md):
+ *  - **Artifact-scoped allowlist** — the token names the EXACT `assetId/filename`
+ *    keys the artifact references (`assets`), not the whole repo. Malicious
+ *    artifact JS holding the token can only re-load the images already on the
+ *    page, not enumerate the repo.
+ *  - **Bound user** — `userId` is re-checked at serve time (`hasRepoAccess`), so
+ *    a token stops working the moment the user loses access (modulo browser
+ *    cache; the serve path uses revalidate+ETag, not immutable).
+ *  - **Purpose-pinned** — verify REJECTS any JWT that isn't `purpose:
+ *    'artifact-asset'`, so a session/OAuth JWT signed with the same secret can
+ *    never satisfy this gate (and this token can never satisfy a session gate).
+ *
+ * Signed with the workspace JWT secret via `authService.getJwtSecret()` — one
+ * rotation lever, same as `asset-upload-token.ts`.
+ *
+ * The token is a bearer credential visible to (untrusted) artifact JS. The
+ * defenses above (narrow asset allowlist + serve-time access re-check + short
+ * TTL) — NOT `connect-src 'none'` — are what make that acceptable: artifact JS
+ * can `postMessage` the token out, but it only unlocks this artifact's own
+ * images for a user who still has access.
+ */
+import jwt from 'jsonwebtoken';
+/** Thrown by `verifyArtifactAssetToken` on tamper / expiry / wrong secret /
+ *  wrong purpose / malformed shape. Callers map it to a fail-closed 404. */
+export class ArtifactAssetTokenError extends Error {
+    code = 'artifact_asset_token_invalid';
+    constructor(message) {
+        super(message);
+        this.name = 'ArtifactAssetTokenError';
+    }
+}
+const PURPOSE = 'artifact-asset';
+export const ARTIFACT_ASSET_TOKEN_TTL_SECONDS = 12 * 60 * 60; // 12h — single source of truth
+export function signArtifactAssetToken(payload, secret) {
+    return jwt.sign(payload, secret, {
+        algorithm: 'HS256',
+        expiresIn: ARTIFACT_ASSET_TOKEN_TTL_SECONDS,
+    });
+}
+/**
+ * Verify a token and return its payload. Throws `ArtifactAssetTokenError` on:
+ *   - tamper (any field mutated) / wrong secret (rotation) / expired / malformed
+ *   - wrong or missing `purpose` (rejects session + OAuth JWTs decisively)
+ *
+ * The caller (asset route, token path) is responsible for the post-verify
+ * checks the signature alone can't make:
+ *   - `payload.repo === row.repo`
+ *   - `${row.assetId}/${row.filename}` ∈ `payload.assets`
+ *   - re-resolve `payload.userId` and re-run `hasRepoAccess`
+ */
+export function verifyArtifactAssetToken(token, secret) {
+    let decoded;
+    try {
+        decoded = jwt.verify(token, secret, { algorithms: ['HS256'] });
+    }
+    catch (err) {
+        throw new ArtifactAssetTokenError(err instanceof Error ? err.message : 'token verification failed');
+    }
+    if (!isPayload(decoded)) {
+        throw new ArtifactAssetTokenError('token payload has unexpected shape or purpose');
+    }
+    return {
+        purpose: PURPOSE,
+        repo: decoded.repo,
+        artifactId: decoded.artifactId,
+        assets: decoded.assets,
+        userId: decoded.userId,
+    };
+}
+/** Build the canonical allowlist key for an asset. Centralized so the mint,
+ *  serve, and tests can't drift on separator/whitespace. */
+export function artifactAssetKey(assetId, filename) {
+    return `${assetId}/${filename}`;
+}
+function isPayload(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (v.purpose === PURPOSE &&
+        typeof v.repo === 'string' && v.repo.length > 0 &&
+        typeof v.artifactId === 'string' && v.artifactId.length > 0 &&
+        Array.isArray(v.assets) && v.assets.every((a) => typeof a === 'string') &&
+        typeof v.userId === 'string' && v.userId.length > 0);
+}
+//# sourceMappingURL=artifact-asset-token.js.map

package/dist/services/artifact-asset-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-asset-token.js","sourceRoot":"","sources":["../../src/services/artifact-asset-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,GAAG,MAAM,cAAc,CAAC;AAE/B;4EAC4E;AAC5E,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,IAAI,GAAG,8BAA8B,CAAC;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAmBD,MAAM,OAAO,GAAG,gBAAyB,CAAC;AAC1C,MAAM,CAAC,MAAM,gCAAgC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,+BAA+B;AAE7F,MAAM,UAAU,sBAAsB,CACpC,OAAkC,EAClC,MAAc;IAEd,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE;QAC/B,SAAS,EAAE,OAAO;QAClB,SAAS,EAAE,gCAAgC;KAC5C,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,MAAc;IAEd,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,uBAAuB,CAC/B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B,CACjE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,uBAAuB,CAAC,+CAA+C,CAAC,CAAC;IACrF,CAAC;IACD,OAAO;QACL,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;AACJ,CAAC;AAED;4DAC4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,QAAgB;IAChE,OAAO,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,CAAC,CAAC,OAAO,KAAK,OAAO;QACrB,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QAC/C,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QACvE,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CACpD,CAAC;AACJ,CAAC"}

package/dist/services/artifact-library-sources.d.ts

@@ -0,0 +1,3 @@
+import type { ArtifactBundle } from '../core/artifact-bundle.js';
+import type { ArtifactLibrarySources } from '../core/artifact-export.js';
+export declare function artifactLibrarySourcesForBundle(bundle: ArtifactBundle): ArtifactLibrarySources;

package/dist/services/artifact-library-sources.js

@@ -0,0 +1,44 @@
+// Server-side artifact library loader. This path is synchronous because the
+// render/export pipeline runs in Node and reads bundled library sources from
+// disk before handing them to Playwright.
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, join } from 'path';
+const require = createRequire(import.meta.url);
+const LIBRARY_PATHS = {
+    d3: 'd3/dist/d3.min.js',
+    motion: 'motion/dist/motion.js',
+    three: 'three/build/three.module.min.js',
+    threeCore: 'three/build/three.core.min.js',
+};
+const cache = {};
+function packageRoot(packageName) {
+    let current = dirname(require.resolve(packageName));
+    while (current !== dirname(current)) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(current, 'package.json'), 'utf8'));
+            if (pkg.name === packageName)
+                return current;
+        }
+        catch {
+        }
+        current = dirname(current);
+    }
+    throw new Error(`Could not resolve package root for ${packageName}`);
+}
+function readLibrarySource(key) {
+    const [packageName, ...parts] = LIBRARY_PATHS[key].split('/');
+    cache[key] ??= readFileSync(join(packageRoot(packageName), ...parts), 'utf8');
+    return cache[key];
+}
+export function artifactLibrarySourcesForBundle(bundle) {
+    const sources = {};
+    for (const key of bundle.libraries ?? []) {
+        sources[key] = readLibrarySource(key);
+        if (key === 'three') {
+            sources.threeCore = readLibrarySource('threeCore');
+        }
+    }
+    return sources;
+}
+//# sourceMappingURL=artifact-library-sources.js.map

package/dist/services/artifact-library-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-library-sources.js","sourceRoot":"","sources":["../../src/services/artifact-library-sources.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAC7E,0CAA0C;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAIrC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,aAAa,GAAG;IACpB,EAAE,EAAE,mBAAmB;IACvB,MAAM,EAAE,uBAAuB;IAC/B,KAAK,EAAE,iCAAiC;IACxC,SAAS,EAAE,+BAA+B;CAClC,CAAC;AAEX,MAAM,KAAK,GAAwD,EAAE,CAAC;AAEtE,SAAS,WAAW,CAAC,WAAmB;IACtC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACpD,OAAO,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAsB,CAAC;YACjG,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW;gBAAE,OAAO,OAAO,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;QACT,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,sCAAsC,WAAW,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,iBAAiB,CAAC,GAA+B;IACxD,MAAM,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9D,KAAK,CAAC,GAAG,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC,GAAG,CAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,MAAsB;IACpE,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YACpB,OAAO,CAAC,SAAS,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/services/artifact-render-export.d.ts

@@ -0,0 +1,97 @@
+import type { ArtifactBundle } from '../core/artifact-bundle.js';
+export declare class ArtifactRenderExportUnavailableError extends Error {
+    constructor(message?: string);
+}
+export interface ArtifactRenderExportOptions {
+    baseUrl?: string;
+    timeoutMs?: number;
+    context?: 'editor' | 'fullscreen' | 'export';
+    onPage?: (page: import('playwright').Page) => void | Promise<void>;
+    /** Artifact-asset capability token so the headless page (no session cookie)
+     *  can load workspace images via `/api/assets/...?at=`. */
+    assetToken?: string;
+}
+export interface ArtifactPngExportFile {
+    index: number;
+    bytes: Buffer;
+}
+export interface NamedArtifactPngExportFile extends ArtifactPngExportFile {
+    filename: string;
+}
+export interface ArtifactInspectOptions extends Omit<ArtifactRenderExportOptions, 'context'> {
+    context?: 'editor' | 'fullscreen';
+    frameSelector?: string;
+    frameIndexes?: number[];
+    maxFrames?: number;
+    includePageScreenshot?: boolean;
+    includeFrameScreenshots?: boolean;
+    screenshotFormat?: 'png' | 'jpeg';
+    jpegQuality?: number;
+}
+export interface ArtifactInspectionImage {
+    mimeType: 'image/png' | 'image/jpeg';
+    byteLength: number;
+    dataUrl: string;
+}
+export interface ArtifactInspectionFrame {
+    index: number;
+    tagName: string;
+    id?: string;
+    className?: string;
+    textSnippet?: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    screenshot?: ArtifactInspectionImage;
+    screenshotError?: string;
+}
+export interface ArtifactInspectionResult {
+    artifactId: string;
+    title: string;
+    kind: string;
+    context: 'editor' | 'fullscreen';
+    viewport: {
+        width: number;
+        height: number;
+    };
+    documentSize: {
+        width: number;
+        height: number;
+    };
+    frameSelector: string;
+    frameCount: number;
+    bodyTextSnippet: string;
+    console: Array<{
+        type: string;
+        text: string;
+    }>;
+    pageErrors: string[];
+    requestFailures: Array<{
+        url: string;
+        errorText: string;
+    }>;
+    screenshot?: ArtifactInspectionImage;
+    frames: ArtifactInspectionFrame[];
+}
+export declare function artifactPngArchiveFilename(bundle: ArtifactBundle): string;
+export declare function artifactPngFrameFilename(bundle: ArtifactBundle, index: number, count: number): string;
+export declare function nameArtifactPngFiles(bundle: ArtifactBundle, files: ArtifactPngExportFile[]): NamedArtifactPngExportFile[];
+/** Zip an arbitrary set of named byte entries. Backing primitive for both the
+ *  multi-PNG archive and the self-contained HTML-export bundle. */
+export declare function zipArtifactFiles(files: Array<{
+    filename: string;
+    bytes: Buffer;
+}>): Promise<Buffer>;
+/** @deprecated naming — use {@link zipArtifactFiles}. Kept for callers. */
+export declare function zipArtifactPngFiles(files: Array<{
+    filename: string;
+    bytes: Buffer;
+}>): Promise<Buffer>;
+export declare function withRenderedArtifact<T>(bundle: ArtifactBundle, options: ArtifactRenderExportOptions, callback: (page: import('playwright').Page) => Promise<T>): Promise<T>;
+export declare function renderArtifactPng(bundle: ArtifactBundle, options?: ArtifactRenderExportOptions): Promise<Buffer>;
+export declare function renderArtifactPngFiles(bundle: ArtifactBundle, options?: ArtifactRenderExportOptions): Promise<ArtifactPngExportFile[]>;
+export declare function renderArtifactPdf(bundle: ArtifactBundle, options?: ArtifactRenderExportOptions): Promise<Buffer>;
+export declare function inspectArtifactRender(bundle: ArtifactBundle, options?: ArtifactInspectOptions): Promise<ArtifactInspectionResult>;