@hyperframes/engine 0.7.107 → 0.7.109

package/dist/utils/renderProvenance.js

@@ -0,0 +1,92 @@
+import { createRequire } from "node:module";
+import { readTagCI } from "./ffprobe.js";
+/**
+ * Hidden render provenance.
+ *
+ * HyperFrames stamps the *container* — never the picture — with the renderer
+ * name and version, so a rendered file carries a machine-readable note about
+ * what produced it, with no visible watermark burned into the frames.
+ *
+ * What goes in is deliberately boring: renderer name and version. No file
+ * paths, usernames, machine names, project names or composition content. Once
+ * a file is distributed the metadata travels with it, and metadata leaks are
+ * hard to walk back.
+ *
+ * **An unauthenticated hint — not an authenticity or attribution boundary.**
+ * These are ordinary unsigned container keys that any tool can write, so a
+ * present tag means the file *claims* to be HyperFrames output, not that
+ * HyperFrames produced it: one `ffmpeg -metadata hyperframes_renderer=...`
+ * forges it. Absence proves just as little, since re-encoding, remuxing, or
+ * any tool that drops unknown keys strips them, and files rendered before this
+ * feature never had them. Good for diagnostics and support ("what wrote this
+ * file?"); never a basis for trust, attribution or licensing decisions in
+ * either direction. Verifiable provenance needs signed claims (C2PA), which
+ * this deliberately is not.
+ */
+export const PROVENANCE_RENDERER_TAG = "hyperframes_renderer";
+export const PROVENANCE_VERSION_TAG = "hyperframes_version";
+export const PROVENANCE_RENDERER_NAME = "hyperframes";
+const UNKNOWN_VERSION = "0.0.0-dev";
+function readEngineVersion() {
+    try {
+        // The engine ships as raw TS and exports "./package.json", so this
+        // resolves without a build-time define. A failed read must never break a
+        // render, hence the fallback rather than a throw.
+        const version = createRequire(import.meta.url)("../../package.json")
+            .version;
+        return typeof version === "string" && version.length > 0 ? version : UNKNOWN_VERSION;
+    }
+    catch {
+        return UNKNOWN_VERSION;
+    }
+}
+export const PROVENANCE_VERSION = readEngineVersion();
+/**
+ * MP4/MOV (the mov muxer family) writes only tags it recognises from a fixed
+ * map and silently discards everything else. WebM/Matroska keeps arbitrary
+ * keys as-is.
+ */
+function isMovFamilyContainer(outputPath) {
+    const lower = outputPath.toLowerCase();
+    return lower.endsWith(".mp4") || lower.endsWith(".mov") || lower.endsWith(".m4v");
+}
+/**
+ * The provenance ffmpeg arguments for a given output container. Place them
+ * before the output path.
+ *
+ * Must be applied on *every* stage that writes an mp4 — encode, mux and the
+ * faststart remux each run their own ffmpeg, and a stage without the flag
+ * drops the tags written by the stage before it.
+ */
+export function renderProvenanceArgs(outputPath) {
+    const args = [
+        "-metadata",
+        `${PROVENANCE_RENDERER_TAG}=${PROVENANCE_RENDERER_NAME}`,
+        "-metadata",
+        `${PROVENANCE_VERSION_TAG}=${PROVENANCE_VERSION}`,
+    ];
+    if (isMovFamilyContainer(outputPath)) {
+        // The additive `+` form is mandatory. A bare `-movflags use_metadata_tags`
+        // *resets* the flag field, silently discarding a `+faststart` set earlier
+        // in the same command — the file still probes fine and keeps its tags,
+        // but the moov atom lands at the end and progressive playback regresses.
+        args.push("-movflags", "+use_metadata_tags");
+    }
+    return args;
+}
+/** Mutating form of {@link renderProvenanceArgs} for push-built arg lists. */
+export function appendRenderProvenanceArgs(args, outputPath) {
+    args.push(...renderProvenanceArgs(outputPath));
+}
+/**
+ * Read provenance back from ffprobe format tags. Matroska uppercases keys on
+ * read while mp4 preserves the case written, so the lookup is
+ * case-insensitive — a case-sensitive read works on mp4 and misses every webm.
+ */
+export function readRenderProvenance(tags) {
+    const renderer = readTagCI(tags, PROVENANCE_RENDERER_TAG);
+    if (renderer === "")
+        return null;
+    return { renderer, version: readTagCI(tags, PROVENANCE_VERSION_TAG) };
+}
+//# sourceMappingURL=renderProvenance.js.map

package/dist/utils/renderProvenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderProvenance.js","sourceRoot":"","sources":["../../src/utils/renderProvenance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAAG,qBAAqB,CAAC;AAC5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAAC;AAEtD,MAAM,eAAe,GAAG,WAAW,CAAC;AAEpC,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,mEAAmE;QACnE,yEAAyE;QACzE,kDAAkD;QAClD,MAAM,OAAO,GAAI,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAA0B;aAC3F,OAAO,CAAC;QACX,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,eAAe,CAAC;IACzB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,EAAE,CAAC;AAEtD;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,UAAkB;IAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACvC,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,MAAM,IAAI,GAAG;QACX,WAAW;QACX,GAAG,uBAAuB,IAAI,wBAAwB,EAAE;QACxD,WAAW;QACX,GAAG,sBAAsB,IAAI,kBAAkB,EAAE;KAClD,CAAC;IAEF,IAAI,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC;QACrC,2EAA2E;QAC3E,0EAA0E;QAC1E,uEAAuE;QACvE,yEAAyE;QACzE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,0BAA0B,CAAC,IAAc,EAAE,UAAkB;IAC3E,IAAI,CAAC,IAAI,CAAC,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC;AACjD,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAoD;IAEpD,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;IAC1D,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,sBAAsB,CAAC,EAAE,CAAC;AACxE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.7.107",
+  "version": "0.7.109",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -38,8 +38,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "^0.7.107",
-    "@hyperframes/parsers": "^0.7.107"
+    "@hyperframes/core": "^0.7.109",
+    "@hyperframes/parsers": "^0.7.109"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",