@hraness/slopcamera 3.2.4

package/apps/desktop/html-overlay/index.ts

@@ -0,0 +1,98 @@
+export {
+  HTML_OVERLAY_MAX_DEVICE_PIXELS_PER_FRAME,
+  HTML_OVERLAY_MAX_DURATION_US,
+  HTML_OVERLAY_MAX_FRAMES,
+  HTML_OVERLAY_MAX_HTML_BYTES,
+  HTML_OVERLAY_MAX_PARAMETER_BYTES,
+  HTML_OVERLAY_MAX_PARAMETER_DEPTH,
+  HTML_OVERLAY_MAX_PARAMETER_NODES,
+  HTML_OVERLAY_MAX_RESOURCES,
+  HTML_OVERLAY_MAX_RESOURCE_BYTES,
+  HTML_OVERLAY_MAX_TOTAL_PIXEL_SAMPLES,
+  HTML_OVERLAY_MAX_TOTAL_RESOURCE_BYTES,
+  HTML_OVERLAY_SCHEMA_VERSION,
+  HtmlOverlayAuthoringInputSchema,
+  HtmlOverlayCanvasSchema,
+  HtmlOverlayDeclaredResourceSchema,
+  HtmlOverlayDeclaredResourcesSchema,
+  HtmlOverlayInlineDocumentSchema,
+  HtmlOverlayParametersSchema,
+  HtmlOverlayRuntimeFrameSchema,
+  HtmlOverlayTimingSchema,
+  createHtmlOverlayRuntimeFrame,
+  htmlOverlayFrameCount,
+  parseHtmlOverlayRuntimeFrame,
+  type HtmlOverlayAuthoringInput,
+  type HtmlOverlayCanvas,
+  type HtmlOverlayDeclaredResource,
+  type HtmlOverlayDeclaredResources,
+  type HtmlOverlayInlineDocument,
+  type HtmlOverlayParameterValue,
+  type HtmlOverlayParameters,
+  type HtmlOverlayRuntimeFrame,
+  type HtmlOverlayTiming,
+} from "./contracts";
+export {
+  HTML_OVERLAY_SCAFFOLD_CLOCK_INTEGRATIONS,
+  HTML_OVERLAY_SCAFFOLD_KINDS,
+  HTML_OVERLAY_SCAFFOLD_PRIMARY_JOBS,
+  HTML_OVERLAY_SCAFFOLD_PROFILES,
+  HTML_OVERLAY_SCAFFOLD_SUBSTRATES,
+  HtmlOverlayScaffoldClockIntegrationSchema,
+  HtmlOverlayScaffoldKindSchema,
+  HtmlOverlayScaffoldPrimaryJobSchema,
+  HtmlOverlayScaffoldProfileSchema,
+  HtmlOverlayScaffoldSubstrateSchema,
+  getHtmlOverlayScaffoldProfile,
+  type HtmlOverlayScaffoldClockIntegration,
+  type HtmlOverlayScaffoldKind,
+  type HtmlOverlayScaffoldPrimaryJob,
+  type HtmlOverlayScaffoldProfile,
+  type HtmlOverlayScaffoldSubstrate,
+} from "./catalog";
+export {
+  ACTIVE_HTML_OVERLAY_LIBRARY_LOCKS,
+  APPROVED_HTML_OVERLAY_LIBRARY_LOCKS,
+  HISTORICAL_HTML_OVERLAY_LIBRARY_LOCKS,
+  HTML_OVERLAY_ASSET_LOCAL_PREFIX,
+  HTML_OVERLAY_LIBRARY_LOCAL_PREFIX,
+  HTML_OVERLAY_LIBRARY_SPECIFIERS,
+  HtmlOverlayActiveLibraryLockSchema,
+  HtmlOverlayActiveLibraryLocksSchema,
+  HtmlOverlayLibraryLockSchema,
+  HtmlOverlayLibraryLocksSchema,
+  HtmlOverlayLibrarySelectionSchema,
+  HtmlOverlayLibrarySpecifierSchema,
+  createHtmlOverlayImportMap,
+  getApprovedHtmlOverlayLibraryLock,
+  htmlOverlayAssetLocalUrl,
+  htmlOverlayLibraryLocalUrl,
+  serializeHtmlOverlayImportMap,
+  type HtmlOverlayActiveLibraryLock,
+  type HtmlOverlayActiveLibraryLocks,
+  type HtmlOverlayImportMap,
+  type HtmlOverlayLibraryLock,
+  type HtmlOverlayLibraryLocks,
+  type HtmlOverlayLibrarySelection,
+  type HtmlOverlayLibrarySpecifier,
+} from "./libraries";
+export {
+  HTML_OVERLAY_RANDOM_ALGORITHM,
+  createHtmlOverlayRandom,
+  htmlOverlayRandomFor,
+} from "./random";
+export {
+  HtmlOverlayBrowserRuntimeConfigSchema,
+  createHtmlOverlayBrowserRuntimeSource,
+  type HtmlOverlayBrowserRuntimeConfig,
+} from "./runtime";
+export {
+  HTML_OVERLAY_TRANSPARENT_RESET_CSS,
+  THREE_REFERENCE_RESOURCE_NAME,
+  THREE_REFERENCE_RESOURCE_URL_PATH,
+  createHtmlOverlayScaffold,
+  createHtmlOverlayScaffoldInput,
+  createThreeReferenceScaffoldInput,
+  type HtmlOverlayScaffoldInput,
+  type ThreeReferenceScaffoldInput,
+} from "./scaffolds";

package/apps/desktop/html-overlay/libraries.ts

@@ -0,0 +1,263 @@
+import { z } from "zod";
+
+import { canonicalJson } from "../core/canonical-json";
+import type { HtmlOverlayDeclaredResource } from "./contracts";
+
+export const HTML_OVERLAY_LIBRARY_SPECIFIERS = Object.freeze([
+  "@paper-design/shaders",
+  "motion",
+  "p5",
+  "two.js",
+  "three",
+  "@sparkjsdev/spark",
+  "three/addons/postprocessing/Pass.js",
+  "vgpu",
+] as const);
+
+export const HtmlOverlayLibrarySpecifierSchema = z.enum(HTML_OVERLAY_LIBRARY_SPECIFIERS);
+export type HtmlOverlayLibrarySpecifier = typeof HTML_OVERLAY_LIBRARY_SPECIFIERS[number];
+
+const MotionLockSchema = z.strictObject({
+  bytes: z.literal(12_098),
+  license: z.literal("MIT"),
+  sha256: z.literal("0d89a96784df54ed726443ebd09be2bee6118d9f1e074166df580bce632c5b62"),
+  specifier: z.literal("motion"),
+  url: z.literal("https://esm.sh/motion@12.42.2/es2022/mini.bundle.mjs"),
+  version: z.literal("12.42.2"),
+});
+
+const PaperShadersLockSchema = z.strictObject({
+  bytes: z.literal(196_909),
+  license: z.literal("Apache-2.0"),
+  sha256: z.literal("4b7f8d053f6c91b4d3ec6abdcfd4b07b9fce7ec2b8086a0f0781f485c59d097e"),
+  specifier: z.literal("@paper-design/shaders"),
+  url: z.literal("https://esm.sh/@paper-design/shaders@0.0.77/es2022/shaders.bundle.mjs"),
+  version: z.literal("0.0.77"),
+});
+
+const P5LockSchema = z.strictObject({
+  bytes: z.literal(1_101_741),
+  license: z.literal("LGPL-2.1"),
+  sha256: z.literal("78062f4b654ec2d7eab8391cb9f960720e90a379789974f27b6fc4aed94fae21"),
+  specifier: z.literal("p5"),
+  url: z.literal("https://cdn.jsdelivr.net/npm/p5@2.3.2/lib/p5.esm.min.js"),
+  version: z.literal("2.3.2"),
+});
+
+const TwoLockSchema = z.strictObject({
+  bytes: z.literal(522_058),
+  license: z.literal("MIT"),
+  sha256: z.literal("0e98a999fcb47006add9425200b18fab26eb09a154665b2893371d74e0a862d4"),
+  specifier: z.literal("two.js"),
+  url: z.literal("https://cdn.jsdelivr.net/npm/two.js@0.8.24/build/two.module.js"),
+  version: z.literal("0.8.24"),
+});
+
+const ThreeLockSchema = z.strictObject({
+  bytes: z.literal(729_954),
+  license: z.literal("MIT"),
+  sha256: z.literal("12e6dd7a5cceb3efd76f8c65acbf5aa55c74820115d9ebae874b28456b9ddb5c"),
+  specifier: z.literal("three"),
+  url: z.literal("https://esm.sh/three@0.185.1/es2022/three.bundle.mjs"),
+  version: z.literal("0.185.1"),
+});
+
+const VgpuLockSchema = z.strictObject({
+  bytes: z.literal(181_522),
+  license: z.literal("MIT"),
+  sha256: z.literal("f7ef874ca3dd29b165beaaf77297d64e06b65db1c48819ac472446da46f2cc9f"),
+  specifier: z.literal("vgpu"),
+  url: z.literal("https://esm.sh/vgpu@0.3.1/es2022/vgpu.bundle.mjs"),
+  version: z.literal("0.3.1"),
+});
+
+const SparkLockSchema = z.strictObject({
+  bytes: z.literal(5_063_871), license: z.literal("MIT"),
+  sha256: z.literal("70050257ce2326c2ce1d2688e6f58987147adf764f8ff7ba4aa17ab7ae5870c0"),
+  specifier: z.literal("@sparkjsdev/spark"), version: z.literal("2.1.0"),
+  url: z.literal("https://esm.sh/@sparkjsdev/spark@2.1.0/X-ZXRocmVl/es2022/spark.bundle.mjs"),
+});
+const ThreePassLockSchema = z.strictObject({
+  bytes: z.literal(840), license: z.literal("MIT"),
+  sha256: z.literal("fc15bae8534b3b21911df509b88b585f1ca375d0bc5047e6bfe07add3403da4b"),
+  specifier: z.literal("three/addons/postprocessing/Pass.js"), version: z.literal("0.185.1"),
+  url: z.literal("https://esm.sh/three@0.185.1/X-ZXRocmVl/es2022/addons/postprocessing/Pass.bundle.mjs"),
+});
+
+export const HtmlOverlayActiveLibraryLockSchema = z.discriminatedUnion("specifier", [
+  PaperShadersLockSchema,
+  MotionLockSchema,
+  P5LockSchema,
+  TwoLockSchema,
+  ThreeLockSchema,
+  VgpuLockSchema,
+  SparkLockSchema,
+  ThreePassLockSchema,
+]);
+export type HtmlOverlayActiveLibraryLock = Readonly<
+  z.infer<typeof HtmlOverlayActiveLibraryLockSchema>
+>;
+
+/**
+ * Append-only parser for persisted lock evidence. When an active lock advances,
+ * retain its prior literal schema here so an old receipt remains readable.
+ */
+export const HtmlOverlayLibraryLockSchema = z.union([
+  PaperShadersLockSchema,
+  MotionLockSchema,
+  P5LockSchema,
+  TwoLockSchema,
+  ThreeLockSchema,
+  VgpuLockSchema,
+  SparkLockSchema,
+  ThreePassLockSchema,
+]);
+export type HtmlOverlayLibraryLock = Readonly<z.infer<typeof HtmlOverlayLibraryLockSchema>>;
+
+export const ACTIVE_HTML_OVERLAY_LIBRARY_LOCKS = Object.freeze([
+  Object.freeze({ bytes: 5_063_871, license: "MIT", sha256: "70050257ce2326c2ce1d2688e6f58987147adf764f8ff7ba4aa17ab7ae5870c0", specifier: "@sparkjsdev/spark", version: "2.1.0", url: "https://esm.sh/@sparkjsdev/spark@2.1.0/X-ZXRocmVl/es2022/spark.bundle.mjs" }),
+  Object.freeze({ bytes: 840, license: "MIT", sha256: "fc15bae8534b3b21911df509b88b585f1ca375d0bc5047e6bfe07add3403da4b", specifier: "three/addons/postprocessing/Pass.js", version: "0.185.1", url: "https://esm.sh/three@0.185.1/X-ZXRocmVl/es2022/addons/postprocessing/Pass.bundle.mjs" }),
+  Object.freeze({
+    bytes: 196_909,
+    license: "Apache-2.0",
+    sha256: "4b7f8d053f6c91b4d3ec6abdcfd4b07b9fce7ec2b8086a0f0781f485c59d097e",
+    specifier: "@paper-design/shaders",
+    url: "https://esm.sh/@paper-design/shaders@0.0.77/es2022/shaders.bundle.mjs",
+    version: "0.0.77",
+  }),
+  Object.freeze({
+    bytes: 12_098,
+    license: "MIT",
+    sha256: "0d89a96784df54ed726443ebd09be2bee6118d9f1e074166df580bce632c5b62",
+    specifier: "motion",
+    url: "https://esm.sh/motion@12.42.2/es2022/mini.bundle.mjs",
+    version: "12.42.2",
+  }),
+  Object.freeze({
+    bytes: 1_101_741,
+    license: "LGPL-2.1",
+    sha256: "78062f4b654ec2d7eab8391cb9f960720e90a379789974f27b6fc4aed94fae21",
+    specifier: "p5",
+    url: "https://cdn.jsdelivr.net/npm/p5@2.3.2/lib/p5.esm.min.js",
+    version: "2.3.2",
+  }),
+  Object.freeze({
+    bytes: 522_058,
+    license: "MIT",
+    sha256: "0e98a999fcb47006add9425200b18fab26eb09a154665b2893371d74e0a862d4",
+    specifier: "two.js",
+    url: "https://cdn.jsdelivr.net/npm/two.js@0.8.24/build/two.module.js",
+    version: "0.8.24",
+  }),
+  Object.freeze({
+    bytes: 729_954,
+    license: "MIT",
+    sha256: "12e6dd7a5cceb3efd76f8c65acbf5aa55c74820115d9ebae874b28456b9ddb5c",
+    specifier: "three",
+    url: "https://esm.sh/three@0.185.1/es2022/three.bundle.mjs",
+    version: "0.185.1",
+  }),
+  Object.freeze({
+    bytes: 181_522,
+    license: "MIT",
+    sha256: "f7ef874ca3dd29b165beaaf77297d64e06b65db1c48819ac472446da46f2cc9f",
+    specifier: "vgpu",
+    url: "https://esm.sh/vgpu@0.3.1/es2022/vgpu.bundle.mjs",
+    version: "0.3.1",
+  }),
+] as const satisfies readonly HtmlOverlayActiveLibraryLock[]);
+
+/** Existing authoring export; active locks are the complete executable allowlist. */
+export const APPROVED_HTML_OVERLAY_LIBRARY_LOCKS =
+  ACTIVE_HTML_OVERLAY_LIBRARY_LOCKS;
+
+/** Append-only data paired with HtmlOverlayLibraryLockSchema for receipt reads. */
+export const HISTORICAL_HTML_OVERLAY_LIBRARY_LOCKS = Object.freeze([
+  ...ACTIVE_HTML_OVERLAY_LIBRARY_LOCKS,
+] as const satisfies readonly HtmlOverlayLibraryLock[]);
+
+function compareAscii(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export const HtmlOverlayLibrarySelectionSchema = z.array(HtmlOverlayLibrarySpecifierSchema)
+  .max(ACTIVE_HTML_OVERLAY_LIBRARY_LOCKS.length)
+  .superRefine((specifiers, context) => {
+    if (new Set(specifiers).size !== specifiers.length) {
+      context.addIssue({ code: "custom", message: "HTML overlay library specifiers must be unique." });
+    }
+  })
+  .overwrite(specifiers => [...specifiers].sort(compareAscii));
+export type HtmlOverlayLibrarySelection = Readonly<z.infer<typeof HtmlOverlayLibrarySelectionSchema>>;
+
+export const HtmlOverlayActiveLibraryLocksSchema = z.array(HtmlOverlayActiveLibraryLockSchema)
+  .max(ACTIVE_HTML_OVERLAY_LIBRARY_LOCKS.length)
+  .superRefine((locks, context) => {
+    const specifiers = locks.map(lock => lock.specifier);
+    if (new Set(specifiers).size !== specifiers.length) {
+      context.addIssue({ code: "custom", message: "Active HTML overlay library locks must be unique." });
+    }
+  })
+  .overwrite(locks => [...locks].sort((left, right) => compareAscii(left.specifier, right.specifier)));
+export type HtmlOverlayActiveLibraryLocks = Readonly<
+  z.infer<typeof HtmlOverlayActiveLibraryLocksSchema>
+>;
+
+export const HtmlOverlayLibraryLocksSchema = z.array(HtmlOverlayLibraryLockSchema)
+  .max(HISTORICAL_HTML_OVERLAY_LIBRARY_LOCKS.length)
+  .superRefine((locks, context) => {
+    const specifiers = locks.map(lock => lock.specifier);
+    if (new Set(specifiers).size !== specifiers.length) {
+      context.addIssue({ code: "custom", message: "HTML overlay library locks must be unique." });
+    }
+  })
+  .overwrite(locks => [...locks].sort((left, right) => compareAscii(left.specifier, right.specifier)));
+export type HtmlOverlayLibraryLocks = Readonly<z.infer<typeof HtmlOverlayLibraryLocksSchema>>;
+
+export const HTML_OVERLAY_LIBRARY_LOCAL_PREFIX = "/.slopcamera-overlay/libraries/" as const;
+export const HTML_OVERLAY_ASSET_LOCAL_PREFIX = "/.slopcamera-overlay/assets/" as const;
+
+export function getApprovedHtmlOverlayLibraryLock(
+  specifier: HtmlOverlayLibrarySpecifier,
+): HtmlOverlayActiveLibraryLock {
+  const parsed = HtmlOverlayLibrarySpecifierSchema.parse(specifier);
+  const lock = ACTIVE_HTML_OVERLAY_LIBRARY_LOCKS.find(candidate => candidate.specifier === parsed);
+  if (lock === undefined) {
+    throw new RangeError(`HTML overlay library is not approved: ${parsed}`);
+  }
+  return lock;
+}
+
+export function htmlOverlayLibraryLocalUrl(
+  lockOrSpecifier: HtmlOverlayLibraryLock | HtmlOverlayLibrarySpecifier,
+): string {
+  const lock = typeof lockOrSpecifier === "string"
+    ? getApprovedHtmlOverlayLibraryLock(lockOrSpecifier)
+    : HtmlOverlayLibraryLockSchema.parse(lockOrSpecifier);
+  return `${HTML_OVERLAY_LIBRARY_LOCAL_PREFIX}${lock.sha256}.mjs`;
+}
+
+export function htmlOverlayAssetLocalUrl(resource: HtmlOverlayDeclaredResource): string {
+  return `${HTML_OVERLAY_ASSET_LOCAL_PREFIX}${resource.sha256}/${resource.urlPath}`;
+}
+
+export interface HtmlOverlayImportMap {
+  readonly imports: Readonly<Partial<Record<HtmlOverlayLibrarySpecifier, string>>>;
+}
+
+export function createHtmlOverlayImportMap(
+  selection: readonly HtmlOverlayLibrarySpecifier[],
+): HtmlOverlayImportMap {
+  const specifiers = HtmlOverlayLibrarySelectionSchema.parse(selection);
+  const imports: Partial<Record<HtmlOverlayLibrarySpecifier, string>> = {};
+  for (const specifier of specifiers) {
+    imports[specifier] = htmlOverlayLibraryLocalUrl(specifier);
+  }
+  return Object.freeze({ imports: Object.freeze(imports) });
+}
+
+export function serializeHtmlOverlayImportMap(
+  selection: readonly HtmlOverlayLibrarySpecifier[],
+): string {
+  return canonicalJson(createHtmlOverlayImportMap(selection));
+}

package/apps/desktop/html-overlay/random.ts

@@ -0,0 +1,49 @@
+export const HTML_OVERLAY_RANDOM_ALGORITHM = "studio-html-overlay-random-v1" as const;
+
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+const MULBERRY_INCREMENT = 0x6d2b79f5;
+const UINT32_RANGE = 4_294_967_296;
+
+function hashRandomDomain(value: string): number {
+  let hash = FNV_OFFSET_BASIS;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+}
+
+function nextMulberry32(state: number): readonly [number, number] {
+  const nextState = (state + MULBERRY_INCREMENT) >>> 0;
+  let value = nextState;
+  value = Math.imul(value ^ (value >>> 15), value | 1);
+  value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+  return [nextState, ((value ^ (value >>> 14)) >>> 0) / UINT32_RANGE];
+}
+
+function randomSeed(seed: number, namespace: string): number {
+  return hashRandomDomain(`${HTML_OVERLAY_RANDOM_ALGORITHM}\0${seed >>> 0}\0${namespace}`);
+}
+
+/**
+ * Creates the page-lifetime deterministic sequence exposed as
+ * `SlopcameraOverlay.random`. The sequence is intentionally stateful.
+ */
+export function createHtmlOverlayRandom(seed: number): () => number {
+  let state = randomSeed(seed, "sequence");
+  return () => {
+    const [nextState, value] = nextMulberry32(state);
+    state = nextState;
+    return value;
+  };
+}
+
+/**
+ * Returns a stateless, domain-separated value for absolute-frame authoring.
+ * Its result is independent of calls to `createHtmlOverlayRandom`.
+ */
+export function htmlOverlayRandomFor(seed: number, key: string): number {
+  const [, value] = nextMulberry32(randomSeed(seed, `key\0${key}`));
+  return value;
+}