@hypit/hypit 0.1.14 → 0.2.0

package/README.md

@@ -110,7 +110,7 @@ Drop in a video and your agent clones the whole workflow — or describe what yo
 
 ## Stay Tuned with Us
 
-Star us, and you will receive all release notifications from GitHub without any delay!
+Star Hypit to bookmark the project. To receive release notifications, select **Watch → Custom → Releases** on GitHub.
 
 ![Stay tuned with us](https://storage.googleapis.com/hypit-public-assets/showcase/npm/2026-09-10/star.gif)
 
@@ -151,7 +151,7 @@ commands and the repository layout.
     <td width="220" align="center">
       <a href="https://openagents.org/blog/posts/2026-09-08-pilot-user-program-zh-hypit"><img alt="OpenAgents" src="./docs/public/openagents.png" width="180"></a>
     </td>
-    <td>OpenAgents Workspace is a product that helps you manage AI agents, allowing you to invoke agents running on any device (whether on a mobile phone or computer) anytime, anywhere. Agents can collaborate within the platform to help you complete tasks and boost efficiency. It currently supports integration with over 20 types of agents, including Claude, Codex, OpenClaw, and Hermes (Details on supported models: <a href="https://api-gateway.openagents.org/static/index.html">https://api-gateway.openagents.org/static/index.html</a>)</td>
+    <td>OpenAgents Workspace is a product that helps you manage AI agents, allowing you to invoke agents running on any device (whether on a mobile phone or computer) anytime, anywhere. Agents can collaborate within the platform to help you complete tasks and boost efficiency. It currently supports integration with over 20 types of agents, including Claude, Codex, OpenClaw, and Hermes (<a href="https://openagents.org">https://openagents.org</a>)</td>
   </tr>
   <tr>
     <td width="220" align="center">

package/dist/public/browser-capture.d.ts

@@ -1,10 +1,16 @@
 import { LaunchOptions, Browser, Page, ScreenshotOptions, RecordOptions } from 'puppeteer-core';
 
-declare function captureBrowserExecutablePath(): Promise<string>;
+type CaptureBrowserOptions = {
+    readonly version?: string;
+    readonly cacheDirectory?: string;
+    readonly downloadBaseUrl?: string;
+};
+declare function captureBrowserExecutablePath(options?: CaptureBrowserOptions): Promise<string>;
 /** Explicit setup, using Puppeteer's cache configuration and upstream browser installer. */
-declare function installCaptureBrowser(): Promise<string>;
+declare function installCaptureBrowser(options?: CaptureBrowserOptions): Promise<string>;
 
 type CaptureOptions = {
+    readonly browser?: CaptureBrowserOptions;
     /** Ordinary Puppeteer launch options, including channel, executablePath and defaultViewport. */
     readonly launch?: LaunchOptions;
     /** Page operation and navigation timeout; Puppeteer's default applies when omitted. */
@@ -53,4 +59,4 @@ type CaptureScript = (context: CaptureScriptContext) => Promise<void>;
 declare function withCapture(options: CaptureOptions, task: (session: CaptureSession) => Promise<void>, onOutput?: (output: CaptureOutput) => void): Promise<readonly CaptureOutput[]>;
 
 export { captureBrowserExecutablePath, installCaptureBrowser, withCapture };
-export type { CaptureOptions, CaptureOutput, CaptureRecording, CaptureScript, CaptureScriptContext, CaptureSession, RecordingCaptureOptions, ScreenshotCaptureOptions };
+export type { CaptureBrowserOptions, CaptureOptions, CaptureOutput, CaptureRecording, CaptureScript, CaptureScriptContext, CaptureSession, RecordingCaptureOptions, ScreenshotCaptureOptions };

package/dist/public/caption.d.ts

@@ -187,6 +187,8 @@ type NarrativeMoment = {
 };
 /** One author-visible word surface. Punctuation owned by the surface is preserved. */
 type CaptionDisplayWord = {
+    /** Authored display separator from the preceding word; ignored at a displayed line start. */
+    readonly separatorBefore: "" | " ";
     readonly id: string;
     readonly unitId: string;
     readonly segmentId: string;

package/dist/public/narrative.d.ts

@@ -220,6 +220,8 @@ type NarrativeMomentRef = NarrativeMoment & {
 };
 /** One author-visible word surface. Punctuation owned by the surface is preserved. */
 type CaptionDisplayWord = {
+    /** Authored display separator from the preceding word; ignored at a displayed line start. */
+    readonly separatorBefore: "" | " ";
     readonly id: string;
     readonly unitId: string;
     readonly segmentId: string;

package/dist/public/runtime-kit.d.ts

@@ -358,11 +358,11 @@ type ManagedProgramCommand = {
     readonly env?: Readonly<Record<string, string>>;
 };
 type ManagedProgramInstallation = {
-    /** Truthful inspection of the installed program; no installer-owned receipt. */
+    /** Read-only inspection of the selected environment and resources; no downloads or receipts. */
     probe(): Promise<ManagedProgramState>;
     /** Reconcile an installed environment before a cold start, using its package manager's cache. */
     readonly prepareBeforeStart?: boolean;
-    /** Commands run when installation is missing, or before a cold start when requested above. */
+    /** Explicit preparation commands, run for missing resources or cold reconciliation above. */
     readonly commands: readonly ManagedProgramCommand[];
 };
 type ManagedProgramState = {

package/dist/public/speech.d.ts

@@ -291,6 +291,8 @@ type NarrativeMoment = {
 };
 /** One author-visible word surface. Punctuation owned by the surface is preserved. */
 type CaptionDisplayWord = {
+    /** Authored display separator from the preceding word; ignored at a displayed line start. */
+    readonly separatorBefore: "" | " ";
     readonly id: string;
     readonly unitId: string;
     readonly segmentId: string;

package/examples/semantic-composition/packages/responsive-explainer/README.md

@@ -30,7 +30,7 @@ With prepared Takes, a Canvas and an exact FontStack already available:
 ```
 
 `during` also accepts a Script Selection or Segment; the shared Window syntax supports other authored
-intervals. `reveal` selects a Script Moment, such as `@demonstrate!` before the relevant word. Rewriting
+intervals. `reveal` selects a Script Moment, such as `@{demonstrate!}` before the relevant word. Rewriting
 the Script or using another delivery changes the projected frame while retaining the layout behavior.
 `transition-frames` is the duration of that change, separate from the scene's lifetime. `stack-order`
 places this scene among other contributions. The caller supplies its title and exact fonts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/browser-capture/README.md

@@ -11,8 +11,13 @@ needs no browser-library installation or private `node_modules` import path.
 `hypit capture install-browser` explicitly prepares the package's tested Chrome for Testing revision
 in the browser cache (`PUPPETEER_CACHE_DIR`, or `~/.cache/puppeteer`).
 `captureBrowserExecutablePath()` reports that path.
-The package pins Chrome 153.0.8010.12 for the native recording API; `installCaptureBrowser()` uses
-the upstream installer. Existing compatible browsers remain selectable through launch options.
+The recommended version is declared in this package's `package.json` under `hypit.captureBrowser`.
+`installCaptureBrowser()` uses the upstream installer. Both it and `captureBrowserExecutablePath()`
+accept `{ version, cacheDirectory, downloadBaseUrl }`; capture accepts the same selection as
+`options.browser`. CLI equivalents are `--browser-version`, `--browser-cache` and
+`--browser-download-base-url`. A custom download base must serve the upstream archive layout;
+there is no retry against an unselected source. Use the same version and cache when preparing and
+capturing. Capture never installs a browser, and a missing selected executable is an error. Existing compatible browsers remain selectable through launch options.
 
 ## Library
 
@@ -26,6 +31,8 @@ file as it finishes. A task failure closes the browser while preserving earlier
   `defaultViewport` replaces it. `channel` selects an installed Chrome channel, `executablePath`
   selects a specific executable, and the default uses this package's tested Chrome for Testing.
   `PUPPETEER_CACHE_DIR` selects the cache directory.
+- `browser`: managed browser version/cache selection. It cannot be combined with an explicit
+  `launch.channel` or `launch.executablePath`.
 - `timeoutMs`: operation and navigation timeout for the initial page. Omission keeps Puppeteer's
   default; `0` disables that timeout. Scripts can configure other pages themselves.
 - `ffprobePath`: metadata reader for finished recordings; defaults to `ffprobe` on `PATH`.

package/packages/browser-capture/package.json

@@ -11,5 +11,10 @@
     "@puppeteer/browsers": "3.2.2",
     "puppeteer-core": "25.10.0",
     "sharp": "0.35.4"
+  },
+  "hypit": {
+    "captureBrowser": {
+      "version": "153.0.8010.12"
+    }
   }
 }

package/packages/browser-capture/src/browser.ts

@@ -1,19 +1,33 @@
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { Browser, computeExecutablePath, install } from "@puppeteer/browsers";
 
-// Page.record uses Chrome's native recording protocol, introduced in Chrome 153.
-// This package owns its tested browser revision independently of other renderers.
-const chromeVersion = "153.0.8010.12";
+export type CaptureBrowserOptions = {
+  readonly version?: string;
+  readonly cacheDirectory?: string;
+  readonly downloadBaseUrl?: string;
+};
 
-const cacheDirectory = () => process.env.PUPPETEER_CACHE_DIR ?? join(homedir(), ".cache", "puppeteer");
+function selection(options: CaptureBrowserOptions) {
+  const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+    hypit?: { captureBrowser?: { version?: string } };
+  };
+  const buildId = options.version ?? manifest.hypit?.captureBrowser?.version;
+  if (typeof buildId !== "string" || !/^\d+\.\d+\.\d+\.\d+$/u.test(buildId)) throw new Error("Capture browser requires an exact four-part version");
+  const cacheDir = options.cacheDirectory ?? process.env.PUPPETEER_CACHE_DIR ?? join(homedir(), ".cache", "puppeteer");
+  return { browser: Browser.CHROME, buildId, cacheDir };
+}
 
-export async function captureBrowserExecutablePath(): Promise<string> {
-  return computeExecutablePath({ browser: Browser.CHROME, buildId: chromeVersion, cacheDir: cacheDirectory() });
+export async function captureBrowserExecutablePath(options: CaptureBrowserOptions = {}): Promise<string> {
+  return computeExecutablePath(selection(options));
 }
 
 /** Explicit setup, using Puppeteer's cache configuration and upstream browser installer. */
-export async function installCaptureBrowser(): Promise<string> {
-  const installed = await install({ browser: Browser.CHROME, buildId: chromeVersion, cacheDir: cacheDirectory() });
+export async function installCaptureBrowser(options: CaptureBrowserOptions = {}): Promise<string> {
+  if (options.downloadBaseUrl !== undefined && !["https:", "http:"].includes(new URL(options.downloadBaseUrl).protocol)) {
+    throw new Error("Capture browser download source must use HTTP or HTTPS");
+  }
+  const installed = await install({ ...selection(options), ...(options.downloadBaseUrl === undefined ? {} : { baseUrl: options.downloadBaseUrl }) });
   return installed.executablePath;
 }

package/packages/browser-capture/src/index.ts

@@ -10,7 +10,10 @@ import sharp from "sharp";
 import { captureBrowserExecutablePath } from "./browser.js";
 export { captureBrowserExecutablePath, installCaptureBrowser } from "./browser.js";
 
+export type { CaptureBrowserOptions } from "./browser.js";
+
 export type CaptureOptions = {
+  readonly browser?: import("./browser.js").CaptureBrowserOptions;
   /** Ordinary Puppeteer launch options, including channel, executablePath and defaultViewport. */
   readonly launch?: LaunchOptions;
   /** Page operation and navigation timeout; Puppeteer's default applies when omitted. */
@@ -99,10 +102,13 @@ export async function withCapture(
   onOutput?: (output: CaptureOutput) => void,
 ): Promise<readonly CaptureOutput[]> {
   const launch = { ...options.launch };
+  if ((launch.channel || launch.executablePath) && options.browser !== undefined) {
+    throw new Error("Choose a managed capture browser or an explicit launch browser, not both");
+  }
   if (!launch.channel && !launch.executablePath) {
-    launch.executablePath = await captureBrowserExecutablePath();
+    launch.executablePath = await captureBrowserExecutablePath(options.browser);
     if (!existsSync(launch.executablePath)) throw new Error(
-      `Capture browser is not installed at ${launch.executablePath}. Run hypit capture install-browser, or select an installed compatible browser.`);
+      `Capture browser is not installed at ${launch.executablePath}. Run hypit capture install-browser with the same version and cache selection, or select an installed compatible browser.`);
   }
   const browser = await puppeteer.launch({
     defaultViewport: { width: 1280, height: 720, deviceScaleFactor: 1 },

package/packages/caption/README.md

@@ -7,7 +7,7 @@ Caption has two independent structures: Script organizes displayed words into Cu
 choose how those Cues appear. A Use may begin inside a Cue. It changes presentation without changing
 that Cue's text or restarting its word timing.
 
-`CaptionDocument` owns displayed words, display/pronunciation associations, word attributes and `||`
+`CaptionDocument` owns displayed words with authored separators, display/pronunciation associations, word attributes and `||`
 breaks. `Timeline` owns placed Takes and measured word times. `temporalizeCaptionDocument(document,
 timeline)` joins their identities and returns `TimedCaptionProjection`: complete Cues with original
 unit times. Segment, speaking-turn and explicit Cue boundaries organize this content. No Style is

package/packages/caption/src/display.ts

@@ -8,6 +8,7 @@ function assert(condition: unknown, message: string): asserts condition {
 export function assertCaptionDocument(value: CaptionDocument): void {
   assert(value.id.length > 0, "CaptionDocument identity is invalid");
   assert(value.units.length > 0 && value.words.length > 0, "CaptionDocument is empty");
+  for (const word of value.words) assert(word.separatorBefore === "" || word.separatorBefore === " ", "Caption word must declare its authored separator");
   const words = new Map(value.words.map((word) => [word.id, word]));
   assert(words.size === value.words.length, "CaptionDocument word ids are repeated");
   const units = new Set<string>();

package/packages/caption-fine/README.md

@@ -82,8 +82,8 @@ caption.primary {
 
 ## Language, spacing and line layout
 
-The same Caption pipeline serves English and Chinese. Script emits English lexical words and
-individual Han characters as Display Words; punctuation stays with its display word. Fine uses
+The same Caption pipeline serves authored text across writing systems. Script emits lexical words
+and individual Han characters as Display Words; punctuation stays with its display word. Fine uses
 those units for timing and active Paint, while authored Cues remain complete reading phrases.
 Dual Text retains its complete alignment unit even when it displays or speaks several words.
 
@@ -94,9 +94,23 @@ explicit authored group, not a renderer-selected segmentation, and does not intr
 The underlying character anchors remain available to other Timeline consumers. `wipe` and
 `typewriter` still animate inside the complete unit over its interval when deliberately selected.
 
-`word-gap` applies between Latin words and at Chinese/Latin boundaries. Adjacent Han characters and
-full-width punctuation carry no extra word gap. `letter-spacing` controls glyph tracking. Exact
-font fallbacks supply the required glyphs; the layout does not select a font by language.
+`word-gap` sizes the separators authored in `CaptionDisplayWord.separatorBefore`. A numeric or
+writing-system boundary does not create a space: `3D` and `3개월` stay joined, while `是的 就是这样`
+keeps its space. Base text, active text, underlines and joined boxes consume the same boundaries.
+For `active-box: trail; active-box-continuity: joined`, Fine measures the complete stationary Cue,
+including the inactive suffix, and joins its painted line rectangles. An over-wide word's internal
+lines are included. Padding and borders extend beyond those rectangles without changing text flow;
+overlapping line backgrounds share one outline and paint translucent color once. Cue motion then
+moves text and decoration together.
+
+This decoration uses HyperFrames' existing local browser-program extension, owned by Fine. Its
+measurement copy uses the same exact-font text and available width, is removed synchronously after
+measurement, and is recomputed when a frame is sought (including after fonts finish loading). It
+adds no layout records to Script, Caption, Timeline or Runtime. Other backends must support the
+selected program format explicitly.
+
+`letter-spacing` controls glyph tracking. Exact font fallbacks supply the required glyphs; the layout
+does not select a font by language.
 
 | Control | Behavior |
 | --- | --- |

package/packages/caption-fine/package.json

@@ -15,6 +15,7 @@
     "@hypit/component-kit": "workspace:*",
     "@hypit/composition": "workspace:*",
     "@hypit/elaborator": "workspace:*",
+    "@hypit/hyperframes": "workspace:*",
     "@hypit/media": "workspace:*",
     "@hypit/narrative": "workspace:*",
     "@hypit/program-space": "workspace:*",

package/packages/caption-fine/src/joined-box.ts

@@ -0,0 +1,114 @@
+/**
+ * Fine's joined decoration is measured after browser layout. Its temporary, untransformed copy
+ * uses the same exact-font children and content width, so Cue motion cannot distort measurements.
+ * Nothing is retained outside the program or written back into Script/Caption/Timeline.
+ */
+export const joinedBoxSetup = String.raw`
+const layout = root.querySelector('[data-fine-box-layout]');
+const layers = [...root.querySelectorAll('[data-caption-active-box="joined"]')];
+const ns = 'http://www.w3.org/2000/svg';
+const paths = layers.map(layer => {
+  const svg = document.createElementNS(ns, 'svg');
+  svg.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;overflow:visible';
+  const path = document.createElementNS(ns, 'path');
+  path.setAttribute('fill', data.background);
+  path.setAttribute('stroke', data.borderColor);
+  path.setAttribute('stroke-width', String(data.borderWidth));
+  svg.append(path); layer.append(svg); return path;
+});
+// Union on actual rectangle edges. Tracing only the exterior removes internal borders and
+// paints translucent fills once, including where line padding overlaps the neighbouring line.
+const outline = rectangles => {
+  const xs = [...new Set(rectangles.flatMap(r => [r.left, r.right]))].sort((a,b) => a-b);
+  const ys = [...new Set(rectangles.flatMap(r => [r.top, r.bottom]))].sort((a,b) => a-b);
+  const cells = ys.slice(1).map((_, y) => xs.slice(1).map((_, x) => rectangles.some(r =>
+    r.left <= xs[x] && r.right >= xs[x+1] && r.top <= ys[y] && r.bottom >= ys[y+1])));
+  const edges = new Map();
+  const key = (x,y) => x+','+y;
+  const add = (x,y,ex,ey) => {
+    const k = key(x,y), list = edges.get(k) || [];
+    list.push([ex,ey]); edges.set(k,list);
+  };
+  for (let y=0;y<cells.length;y++) for (let x=0;x<cells[y].length;x++) {
+    if (!cells[y][x]) continue;
+    if (!cells[y-1]?.[x]) add(x,y,x+1,y);
+    if (!cells[y]?.[x+1]) add(x+1,y,x+1,y+1);
+    if (!cells[y+1]?.[x]) add(x+1,y+1,x,y+1);
+    if (!cells[y]?.[x-1]) add(x,y+1,x,y);
+  }
+  const contours = [];
+  while (edges.size) {
+    const start = edges.keys().next().value.split(',').map(Number);
+    const points = []; let current = start, previous;
+    do {
+      points.push([xs[current[0]],ys[current[1]]]);
+      const k = key(...current), next = edges.get(k);
+      let index = 0;
+      if (next.length > 1 && previous) {
+        const dx = current[0]-previous[0], dy = current[1]-previous[1];
+        // At a point contact, keep each contour on its own side of the corner.
+        index = next.findIndex(p => dx*(p[1]-current[1])-dy*(p[0]-current[0]) > 0);
+        if (index < 0) index = 0;
+      }
+      const target = next.splice(index,1)[0];
+      if (!next.length) edges.delete(k);
+      previous = current; current = target;
+    } while (current[0] !== start[0] || current[1] !== start[1]);
+    const corners = points.filter((p,i) => {
+      const a = points[(i+points.length-1)%points.length], b = points[(i+1)%points.length];
+      return (p[0]-a[0])*(b[1]-p[1]) !== (p[1]-a[1])*(b[0]-p[0]);
+    });
+    const rounded = corners.map((p,i) => {
+      const a = corners[(i+corners.length-1)%corners.length], b = corners[(i+1)%corners.length];
+      const before = Math.hypot(p[0]-a[0],p[1]-a[1]), after = Math.hypot(b[0]-p[0],b[1]-p[1]);
+      const radius = Math.min(data.radius, before/2, after/2);
+      return { p, start: [p[0]+(a[0]-p[0])*radius/before,p[1]+(a[1]-p[1])*radius/before],
+        end: [p[0]+(b[0]-p[0])*radius/after,p[1]+(b[1]-p[1])*radius/after], radius,
+        turn: (p[0]-a[0])*(b[1]-p[1])-(p[1]-a[1])*(b[0]-p[0]) };
+    });
+    contours.push(rounded.map((c,i) => (i ? 'L' : 'M')+c.start.join(' ')
+      +(c.radius ? 'A'+c.radius+' '+c.radius+' 0 0 '+(c.turn>0 ? 1 : 0)+' '+c.end.join(' ') : '')).join(' ')+'Z');
+  }
+  return contours.join(' ');
+};
+return () => {
+  const measure = layout.cloneNode(true);
+  // Exact font declarations are already inline on the typed text children. Copy the inherited
+  // flow properties explicitly; the measurement must not inherit the document body's typography.
+  const style = getComputedStyle(layout);
+  const rootStyle = getComputedStyle(root);
+  const offsetX = parseFloat(rootStyle.paddingLeft), offsetY = parseFloat(rootStyle.paddingTop);
+  for (const name of ['font-size','line-height','text-align','direction','letter-spacing','word-spacing']) {
+    measure.style.setProperty(name,style.getPropertyValue(name));
+  }
+  measure.style.cssText += ';position:fixed;left:0;top:0;margin:0;padding:0;border:0;box-sizing:content-box;'
+    +'width:'+style.width+';height:auto;max-width:none;transform:none;visibility:hidden;pointer-events:none';
+  measure.removeAttribute('id');
+  for (const child of measure.querySelectorAll('[id]')) child.removeAttribute('id');
+  document.body.append(measure);
+  let words;
+  try {
+    const origin = measure.getBoundingClientRect();
+    words = [...measure.querySelectorAll('[data-fine-box-word]')].map(word => {
+      const range = document.createRange(); range.selectNodeContents(word);
+      return [...range.getClientRects()].filter(r => r.width > 0 && r.height > 0).map(r => ({
+        left:r.left-origin.left+offsetX, right:r.right-origin.left+offsetX,
+        top:r.top-origin.top+offsetY, bottom:r.bottom-origin.top+offsetY,
+      }));
+    });
+  } finally { measure.remove(); }
+  const lines = new Map(); let wordIndex = 0;
+  for (let index=0;index<paths.length;index++) {
+    for (let count=0;count<data.wordCounts[index];count++) for (const rect of words[wordIndex++]) {
+      const line = lines.get(rect.top);
+      if (!line) lines.set(rect.top,{...rect});
+      else { line.left=Math.min(line.left,rect.left); line.right=Math.max(line.right,rect.right);
+        line.bottom=Math.max(line.bottom,rect.bottom); }
+    }
+    paths[index].setAttribute('d',outline([...lines.values()].map(r => ({
+      left:r.left-data.paddingX-data.borderWidth/2, right:r.right+data.paddingX+data.borderWidth/2,
+      top:r.top-data.paddingY-data.borderWidth/2, bottom:r.bottom+data.paddingY+data.borderWidth/2,
+    }))));
+  }
+};
+`;

package/packages/caption-fine/src/manifest.ts

@@ -75,7 +75,7 @@ export const captionFineMarkupSurfaces = [
               { name: "letter-spacing", required: false, fallback: "0",
                 summary: "Adds pixels of tracking between glyphs." },
               { name: "word-gap", required: false, fallback: "a quarter of size",
-                summary: "Sets pixel spacing between Latin words and at Chinese/Latin boundaries. Adjacent Han characters and full-width punctuation have no extra word gap; use letter-spacing for tracking." },
+                summary: "Sets the pixel width of authored display separators. Writing-system and numeric boundaries do not create spaces; use letter-spacing for glyph tracking." },
               { name: "size", required: true,
                 summary: "Sets the type size in pixels." },
               { name: "kerning", required: false, values: ["auto", "normal", "none"], fallback: "auto",