Files
hyperframes/packages/share/README.md
T
terencecho 04947d99f7 feat(cli): share rendered videos through unified reviews (#7135)
* feat(cli): share rendered videos through unified reviews (#7135)

* feat(share): attach editable project sources to reviews (#7137)

* feat(share): measure local sharing outcomes (#7138)

* feat(cli): stage the sixty-day publish transition (#7136)

* feat(studio): share review pages from local preview (#7140)

Advertise the CLI sharing bridge before bootstrapping it so standalone Studio does not
request unsupported routes. Preserve origin and session checks.

Budget the intended sharing artifact: clean main packs at 8,060,519 bytes versus
8,162,979 with sharing (8,169,168 in CI). Required policy and Unicode tables, bundled
sharing code, and Studio controls account for the growth. Set the packed-only budget
to 8,577,627, following the 5% headroom convention; retain the unpacked cap and all
package checks.

* fix(share): persist refusals and improve CLI retry feedback

* fix(ci): restore render diagnostics and include sharing workspace

* fix(cli): keep sharing owner error codes stable

* fix(share): clarify update feedback and align audience changes

* fix(share): clarify updates and avoid scratch-file rerenders

* fix(cli): report active shares and preserve update channels

* fix(cli): resolve update channel when checking registry

* fix(ci): refresh sharing package budgets after rebase

* fix(share): require consent before uploading project files
2026-11-11 06:26:24 +00:00

114 lines
9.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# @hyperframes/share
Node-only sharing kernel for Desktop, the CLI and local Studio's server. All hosts use the same review project, link settings, video versions and persisted retry state. This package does not render videos, sign users in, or define plan policy.
```js
import {
bindShareHost,
reviewClient,
signedInRequest,
projectFingerprint,
shareForReview,
addVersion,
reviewStatus,
reviewVersion,
} from "@hyperframes/share";
bindShareHost({
normalize: realpathSync,
channelSite: "https://hyperframes.dev",
signinSites: ["https://hyperframes.dev"],
reviewUploadOrigins: ["https://review-bucket.s3.us-east-1.amazonaws.com"],
signedInRequest,
projectFingerprint,
latestExportFile, // (dir) => { path, fingerprint, id } | null
ffBinary, // ('ffprobe') => executable path
});
const client = reviewClient({ access, signedInEmail });
const share = await shareForReview({ projectPath, title, client, audience: "public" });
await addVersion({ projectPath, title, client, onProgress });
const [current, version] = await Promise.all([
reviewStatus({ projectPath, client }),
reviewVersion(projectPath),
]);
```
`access(refusedToken?)` returns `{ token, heygen, heygenApi, owner }` or null. It is read for every request. A refused bearer is passed back so the host can refresh it. `heygen` is the review API base. A host can inject its own `signedInRequest` to retain network tracing. `execFile` can likewise be injected to retain native process policy.
Video and source uploads require exact storage origins from trusted host configuration. Set `reviewUploadOrigins` on the host or supply a comma-separated `HYPERFRAMES_REVIEW_UPLOAD_ORIGINS` environment variable. Configure the bucket-specific HTTPS origins used by the signer. Use URL origins without paths, trailing slashes, or wildcards. Local tests can explicitly allow an HTTP origin on `127.0.0.1`. An empty list refuses every upload.
Before first registration the host must obtain explicit audience consent. For a video share, prepare a current MP4, call `shareForReview`, then await `addVersion` and check the latest ready version before reporting success. `shareForReview` registers or enables the link. Hosts can pass `beforeOpen(projectId)` to prepare or validate other review content, such as a synced storyboard. The hook runs under the review lock after registration is saved, only for the first opening or when reopening a revoked link, before link or audience changes. An already-open link returns its status without running the hook. If preparation fails, retry uses the same registration, so the hook must be safe to retry. Keep the hook short because it holds the review lock. That lock is not reentrant: the hook must not call same-project review-lock operations such as `shareForReview`, `setReviewAccess`, `turnOffReviewLink`, `removeReviewProject`, or review-switch operations; they would wait on the hook itself. Use direct client requests for preparation instead.
`addFirstVersion` starts background work and is for long-lived hosts only. `open: () => boolean` on `addVersion` bounds the polling lifetime without discarding the saved operation. `filesForExport(projectPath, renderedFingerprint)` optionally supplies an already-synced matching snapshot. Omit it for ordinary video sharing.
`reviewClient` exposes workspace capabilities, project listing/removal, grants, revision-checked access changes and export operations. `setReviewAccess`, `turnOffReviewLink`, and `removeReviewProject` retain the Desktop behavior. Enabling a revoked link produces a new URL. Disabling keeps the project and comments; removal is a separate operation.
Hosts can sync a renamed project with `client.updateTitle(id, { title, expected_title })`. An optional `fromReview` hook on `addVersion` supplies feedback attribution after sign-in on each send. Pass the same hook to `recheckHeld` or `refreshReviewExport` to clear the recorded activity when a pending version becomes ready.
If a create request had no confirmed outcome, a later refusal keeps the original request and its idempotency key. The original request may still create a version. When the server has no more specific recovery instruction, check the review page and export a new video with different settings before adding another version.
Identity remains in the project’s generated review.json metadata (or the existing backend-specific filename); pending export requests remain in the generated review-export.json metadata. No bearer is stored there. A copied folder must deliberately reset sharing identity when creating a new project; a renamed folder retains it. A malformed/unreadable record fails instead of silently registering a new project. The error identifies the metadata file and asks the owner to restore a backup or contact support to reconnect the existing share; deleting the file can discard recovery state or consume another slot.
Metadata mutations and version uploads use separate cross-process locks under `.hyperframes`. Locks publish complete owner metadata with a hard link or, on volumes that reject hard links, an atomic rename of a directory containing the owner record. The kernel reclaims a recorded owner only when the same machine proves that process is dead. Older clients may report a filesystem error while a fallback directory is held. An empty legacy lock file still requires manual recovery after stopping all sharing processes that can access the project. Interrupted upload operations resume with their saved idempotency keys. Concurrent identical uploads re-read the completed version under the lock and do not create another version.
`snapshotProject` skips symlinks by default, retaining Desktop watcher, change-set and saved-render compatibility; `snapshotFiles` also skips symlink entries. Set `followSymlinks: true` for a link-aware full snapshot. The CLI-facing `projectFingerprint` opts into following linked media (with cycle detection), so edited linked files invalidate its cached render. Both comparisons ignore HTML ID stamps. Export/history metadata, caches, hidden folders and installed packages are excluded. Hosts must record the fingerprint of the actual rendered source and must not relabel an old render with a newer fingerprint.
Public type exports include `ShareHost`, `ReviewClient`, `ReviewShare`, `VersionRequest`, and `Wire`, plus `@hyperframes/share/types/reviewWire` and `types/share`. Per-module entry points preserve Desktop imports during adoption.
## Source snapshots
`shareSources({access, spaceId})` prepares editable source for a rendered version:
```js
const sources = shareSources({ access, spaceId });
const result = await sources.prepare(projectPath, renderedFingerprint);
if (result.at === "ready") {
await addVersion({
projectPath,
title,
client,
filesForExport: sources.filesForExport,
requireSource: true,
});
}
```
Handle `unavailable.reason` before creating the video version. Plan ineligibility
can use video-only; changed source, conflicts and unexpected upload failures need
an explicit choice to omit source. The CLI exposes `--video-only` for that choice.
`filesForExport` only validates already-prepared source; it does not upload.
The adapter uses the portable-source-v4 capture/manifest rules and
multipart transport. The pinned policy, Unicode 15.1 registry (with its license),
and manifest test vectors are checked into this repository. Source is captured through
verified file handles; upload bytes are streamed and checked against their hash.
Workspace limits, upload receipts and published snapshot identity are checked.
Pending uploads retain their original idempotency key across retries. A conflict
is never auto-resolved. When local source changes, the adapter cancels an older
pending upload before starting another; uploads under verification are preserved.
A stalled storage PUT stops after 60 seconds without progress and can retry with
the same upload identity.
Default state uses `.hyperframes/share-sync.<backend-hash>.json`, with strict
account/backend/realpath binding, private atomic writes, and a process lock.
Hosts can inject a compatible `store` or read-only `existingBinding` resolver.
An external Desktop binding is reused only when exact and settled; this adapter
never writes Desktop's binding or starts a second upload on its behalf.
Source sharing requires an authorized account and a workspace that supports editable project files.
Source-plan/feature eligibility remains server controlled. Automated fixtures do
not establish live entitlement, moderation, source download or outside-editor
acceptance. See [the source guide](https://hyperframes.heygen.com/developers/share-source).
Tests run locally without an account or service credentials:
```bash
node --test packages/share/tests/*.test.mjs
bun run --cwd packages/share build
```
The bundled Unicode data records SHA-256 hashes for its inputs in `sources`.
Those files are published in the [Unicode 15.1 database](https://www.unicode.org/Public/15.1.0/ucd/).
Keep the included Unicode license with redistributed data. The pinned version
keeps path comparison consistent across Node versions and operating systems.