Files
hyperframes/packages/share
Michael Wang d5f0b1a5bf fix: nested .hyperframes stays private, capture page server checks Host, project manifests pin no CLI (#7927)
* fix(core): a .hyperframes folder in a subfolder stays private too

The private-file rule treated .hyperframes as the app's records folder only at
the project root. A project copied into a subfolder keeps its own
.hyperframes/, and its chat history, hand-off and other records there were
listed in the file tree and served by Studio's file and preview routes and by
the other file servers that share the rule.

A .hyperframes segment at any depth is now private, in every spelling Windows
opens. Studio's own files and the prepared-assets and requests folders stay
servable only at the root, the one place Studio reads and writes them. The file
tree also skips .hyperframes/backup at any depth.

* fix(cli): the capture --local-file page server answers only its own host

The page server that capture --local-file starts on a loopback port answered a
request whatever its Host header said. A site whose name resolves to 127.0.0.1
could then read the files it serves from the browser.

The server now refuses, before any file lookup, a request whose Host is not its
own loopback name and port, with the same isOwnLoopbackHost rule the static
project server and the engine file server use. Every response carries
X-Content-Type-Options: nosniff. The capture browser loads the page by
127.0.0.1 and its port, and fetchLocalPageUrl reads from disk, so both work as
before.

* fix(skills): a plugin manifest in the project pins no CLI release

The skills launcher read a plugin manifest from the folder above skills/
wherever the skills were installed. For a project-level install that folder is
the project itself or its .agents or .claude folder, so a plugin.json shipped
with a project could pin an old hyperframes release and turn off update checks
and standalone skill refreshes.

The launcher now reads a manifest only from a bundle of its own: a folder whose
name does not start with a dot and that is neither the folder the CLI works in
nor one that contains it. Plugin managers install bundles into their own
folders, so those keep their pin. A manifest anywhere else leaves the call the
same as with no manifest. A manifest that pins a release older than 0.9.34, the
launcher's floor, is refused. The agent-facing plugin rules and the skills
guide say the same.

* fix(skills): a plugin bundle inside the working folder pins only behind a dot folder

A package inside a monorepo could still pin the CLI: with the agent working at
the monorepo root, <mono>/packages/video/plugin.json sat beside a skills folder
the launcher took for a bundle.

The launcher now also refuses a bundle inside the working folder unless a
folder whose name starts with a dot lies between them, as .claude does in
~/.claude/plugins/cache when the agent works in the home folder. Bundles in
~/.claude/plugins, ~/.cursor/plugins and ~/.gemini/extensions keep their pin
from the home folder or a project. The plugin rules and the skills guide now
state the three conditions the launcher checks.

* docs(cli): a .hyperframes folder in a subfolder is left out and not served

The private-file rule now treats a .hyperframes/ folder at any depth as the
app's records. Files stored in one inside a subfolder, assets included, stay out
of uploads and are not served by Studio, preview or render. The cloud render
section now says so beside the rule it already describes.

* fix(cli): capture pages keep loading scripts with no or unlisted extensions

With nosniff on every response, a script the capture page server did not
know the type of (a .cjs file, or a file with no extension) was served as
application/octet-stream, and the browser refused to run it.

The server now names .cjs, .wasm, .xml, source maps, web manifests, CSV,
WebVTT, glTF and more audio, video and image types. A file whose type is still
unlisted is served without nosniff, so the browser sniffs it as it did before
and such a script runs. Every listed type and every empty error response keeps
nosniff.

* fix(share): sync and share leave out a .hyperframes folder below the root

The .hyperframes rules in the source path policy matched only at the project
root, so a copy's records in a subfolder, such as
sub/.hyperframes/agent-runs.jsonl, fell through to the default rule and
travelled with share and sync.

A new nested-hyperframes-state rule leaves out a .hyperframes folder at any
depth below the root. It sits before the first allow rule, as the contract's
rule order requires. The root folder's Studio files and other portable files
travel as before. Stored snapshot reads skip the new rule through
stored_manifest.legacy_rule_regexes, the shape the server and Desktop copies
already use, so snapshots and bindings captured earlier still read.
2026-11-16 07:18:57 +00:00
..
2026-11-16 06:16:47 +00:00

@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.

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:

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.

Tests run locally without an account or service credentials:

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. Keep the included Unicode license with redistributed data. The pinned version keeps path comparison consistent across Node versions and operating systems.