Files
hyperframes/docs/developers/share-source.mdx
T

92 lines
4.9 KiB
Plaintext

---
title: "Editable source in a share"
description: "Choose whether a CLI review includes the project files used by its rendered video."
---
`hyperframes share` can attach editable project files to the same review page
used by Desktop. Source is available when the workspace's sharing and
Composition Sync permissions allow it. The recipient's access still depends on
the share's settings and their plan.
```bash
hyperframes share --public # Video and source when eligible
hyperframes share --update # Update the existing review
hyperframes share --update --video-only # Explicitly omit editable source
```
The five-free-project sharing limit is unchanged. A workspace that cannot use
Composition Sync can still share its rendered video. The command reports
`source.at: "video_only"` and a reason in JSON; this is a successful video share.
A source upload does not grant anyone editing access by itself. Manage access
through `hyperframes share --manage`.
## What travels
Source uses the same portable project policy as Desktop: authored HTML, scripts,
styles, assets, and supported Studio edit metadata. Known credential filenames
(such as `.env`, `.npmrc`, and `*.pem`), dependency directories, chat
history, local sharing state, and recorded render outputs stay out.
These are filename rules, not a secret scanner. `.gitignore` and
`.hyperframesignore` do not control source capture. Other regular files can be
included even if Git ignores them. Keep private material outside the project,
or use `--video-only` when you do not want to upload project files. Unsupported symlinks and invalid file names stop source
preparation rather than silently producing an incomplete editable project.
The upload uses the workspace's file-count, per-file, project-size and manifest
limits. Large media uploads in parts. Only a verified published snapshot that
still matches the rendered project can be attached to the video version. The CLI
checks the contents of rendered assets, including changes that preserve file
sizes and timestamps. Deployments must include the exact source storage origins
in `HYPERFRAMES_REVIEW_UPLOAD_ORIGINS` alongside the video storage origins.
## Interrupted uploads and unavailable source
Retry the same command after a network interruption. Its local record preserves
the composition identity, upload idempotency key and completed file parts.
A storage upload that makes no progress for 60 seconds is stopped and retried
within the retry limit. The source record lives at `.hyperframes/share-sync.<backend-hash>.json` and
contains no sign-in token. Do not copy that record into another project or edit
its account, workspace or path: mismatches stop sharing to avoid overwriting
another project's source.
If source changed, conflicts with another snapshot, or remains under verification,
the command explains why it stopped. Retry after resolving the problem, or pass
`--video-only` to share just the rendered video. An unexpected source upload
failure never silently turns an eligible source share into video-only. If the
server confirms an upload expired or failed, a retry starts a new upload. If
the files changed while an earlier upload was still pending, the CLI cancels
that upload before starting a new one. It waits for uploads already under
verification and preserves conflicts for explicit resolution.
A video-only retry does not resume an interrupted video upload that already
includes source. Check its status before retrying. To publish the same render as
a new video-only version after the earlier upload finishes, use
`hyperframes share --update --video-only`. Previous versions retain their files.
`--status` reads the review without uploading anything. Its source state is
`not_checked`; it does not promise that local files match the shared version.
The upload result uses `ready` only after source verification and attachment
preparation; video readiness remains the separate top-level `ready` field.
## Integrating another local host
`@hyperframes/share` exports `shareSources` and
`createProjectShareSourceStore`. Call `prepare(projectPath, renderedFingerprint)`
before `addVersion`, then pass `filesForExport` and `requireSource: true` for a
ready source result. `requireSource` prevents a later mismatch from degrading to
a video-only version. Pass `omitSource: true` for a video-only operation that
must not reuse a source-bearing version or pending upload.
A host may inject its existing binding store, or supply a read-only
`existingBinding` resolver for Desktop bindings. Exact snapshots can be reused
only in the same account and owner workspace, without a pending sync operation.
Unsynced changes in a Desktop-owned binding require a Desktop sync first. The
standalone CLI keeps its own project-local sync record; it does not discover or
modify Desktop's application data directory.
## Related topics
- [CLI reference](/packages/cli#share) — audiences, updates, and processing status.
- [CLI guide](/developers/cli) — choose the command for your task.