@hypit/hypit 0.0.1 → 0.1.1

package/packages/ranking/src/tier.ts

@@ -0,0 +1,176 @@
+import { resolveTierBoardMotion } from "./schedule.js";
+import type { TierBoardStyle } from "./types.js";
+
+export type TierBoardGeometry = {
+  readonly width: number;
+  readonly height: number;
+  readonly rowHeight: number;
+  readonly labelWidth: number;
+  readonly gap: number;
+  readonly iconSize: number;
+};
+
+export type TierStageGeometry = {
+  readonly centerX: number;
+  readonly centerY: number;
+  readonly size: number;
+};
+
+export type TierCell = {
+  readonly x: number;
+  readonly y: number;
+  readonly size: number;
+};
+
+export type TierItemPose = {
+  readonly x: number;
+  readonly y: number;
+  readonly scale: number;
+  readonly opacity: number;
+  readonly rotateDeg: number;
+  readonly blurPx: number;
+  readonly shadowY: number;
+  readonly shadowBlur: number;
+  readonly shadowOpacity: number;
+};
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function outCubic(value: number): number {
+  return 1 - Math.pow(1 - value, 3);
+}
+
+function smootherStep(value: number): number {
+  return value * value * value * (value * (value * 6 - 15) + 10);
+}
+
+export function tierBoardGeometry(width: number, height: number, style: TierBoardStyle): TierBoardGeometry {
+  const rowHeight = height / style.rows.length;
+  const labelWidth = Math.round(style.labelWidthRatio === undefined
+    ? rowHeight * 1.5
+    : width * style.labelWidthRatio);
+  const gap = Math.max(4, Math.round(rowHeight * 0.03));
+  return {
+    width,
+    height,
+    rowHeight,
+    labelWidth,
+    gap,
+    iconSize: rowHeight - gap * 2,
+  };
+}
+
+export function tierStageGeometry(width: number, height: number, style: TierBoardStyle): TierStageGeometry {
+  return {
+    centerX: Math.round(width * style.stagePoint.x),
+    centerY: Math.round(height * style.stagePoint.y),
+    size: style.stageSizePx,
+  };
+}
+
+export function tierCell(geometry: TierBoardGeometry, rowIndex: number, column: number): TierCell {
+  return {
+    x: geometry.labelWidth + geometry.gap + column * (geometry.iconSize + geometry.gap),
+    y: Math.round(rowIndex * geometry.rowHeight
+      + (geometry.rowHeight - geometry.iconSize) / 2),
+    size: geometry.iconSize,
+  };
+}
+
+function settled(cell: TierCell): TierItemPose {
+  return {
+    x: cell.x,
+    y: cell.y,
+    scale: 1,
+    opacity: 1,
+    rotateDeg: 0,
+    blurPx: 0,
+    shadowY: 7,
+    shadowBlur: 10,
+    shadowOpacity: 0.2,
+  };
+}
+
+export function directTierItemPose(
+  localFrame: number,
+  cell: TierCell,
+  appearFrames: number,
+): TierItemPose {
+  if (localFrame >= appearFrames) return settled(cell);
+  const progress = clamp01(localFrame / appearFrames);
+  const eased = outCubic(progress);
+  const overshoot = Math.sin(Math.PI * progress) * 0.075;
+  return {
+    x: cell.x,
+    y: cell.y,
+    scale: 0.76 + 0.24 * eased + overshoot,
+    opacity: Math.min(1, progress * 4),
+    rotateDeg: 0,
+    blurPx: (1 - eased) * 1.2,
+    shadowY: 12 - 5 * eased,
+    shadowBlur: 18 - 8 * eased,
+    shadowOpacity: 0.28 - 0.08 * eased,
+  };
+}
+
+export function fromHighTierItemPose(
+  localFrame: number,
+  durationFrames: number,
+  stage: TierStageGeometry,
+  cell: TierCell,
+  appearFrames: number,
+  moveFrames: number,
+): TierItemPose {
+  const phases = resolveTierBoardMotion(durationFrames, appearFrames, moveFrames);
+  const stageX = stage.centerX - cell.size / 2;
+  const stageY = stage.centerY - cell.size / 2;
+  const stageScale = stage.size / cell.size;
+  if (localFrame < phases.appearEndFrame) {
+    const progress = clamp01(localFrame / appearFrames);
+    const eased = outCubic(progress);
+    const overshoot = Math.sin(Math.PI * progress) * 0.06;
+    return {
+      x: stageX,
+      y: stageY,
+      scale: stageScale * (0.76 + 0.24 * eased + overshoot),
+      opacity: Math.min(1, progress * 4),
+      rotateDeg: 0,
+      blurPx: (1 - eased) * 1.6,
+      shadowY: 18 - 2 * eased,
+      shadowBlur: 28 - 4 * eased,
+      shadowOpacity: 0.3,
+    };
+  }
+  if (localFrame < phases.moveStartFrame) return {
+    x: stageX,
+    y: stageY,
+    scale: stageScale,
+    opacity: 1,
+    rotateDeg: 0,
+    blurPx: 0,
+    shadowY: 16,
+    shadowBlur: 24,
+    shadowOpacity: 0.3,
+  };
+  if (localFrame < durationFrames) {
+    const actualMoveFrames = (phases.moveEndFrame ?? durationFrames) - phases.moveStartFrame;
+    const progress = clamp01((localFrame - phases.moveStartFrame) / actualMoveFrames);
+    const eased = smootherStep(progress);
+    const arc = Math.sin(Math.PI * eased);
+    const arcHeight = Math.min(48, Math.max(20, Math.abs(cell.y - stageY) * 0.09));
+    return {
+      x: stageX + (cell.x - stageX) * eased,
+      y: stageY + (cell.y - stageY) * eased - arcHeight * arc,
+      scale: stageScale + (1 - stageScale) * eased + 0.025 * arc,
+      opacity: 1,
+      rotateDeg: 0,
+      blurPx: 0,
+      shadowY: 16 - 8 * eased,
+      shadowBlur: 24 - 12 * eased,
+      shadowOpacity: 0.3 - 0.1 * eased,
+    };
+  }
+  return settled(cell);
+}

package/packages/ranking/src/types.ts

@@ -0,0 +1,277 @@
+import type { FrameSpan } from "@hypit/composition";
+import type {
+  FontArtifactRef,
+  SynchronizedMedia,
+} from "@hypit/media";
+import type { BlobRef } from "@hypit/protocol";
+import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
+
+export type RankingVariant = "tier-board" | "column" | "top-three";
+
+export type RankingHeader = {
+  readonly id: string;
+  readonly variant: RankingVariant;
+};
+
+export type TriggeredRankingScheduleEntry = {
+  readonly itemId: string;
+  readonly triggerFrame: number;
+  readonly stage: FrameSpan;
+  readonly cumulative: FrameSpan;
+  readonly settled: FrameSpan;
+};
+
+export type TriggeredRankingSchedule = {
+  readonly id: string;
+  readonly variant: "top-three";
+  readonly outer: FrameSpan;
+  readonly terminalFrame: number;
+  readonly entries: readonly TriggeredRankingScheduleEntry[];
+};
+
+export type TriggeredRankingCandidate = {
+  readonly itemId: string;
+  readonly activation: TemporalInstant;
+};
+
+export type TriggeredRankingCandidateSet = {
+  readonly entries: readonly TriggeredRankingCandidate[];
+};
+
+export type RankingWindowInput = {
+  readonly itemId: string;
+  readonly window: TemporalWindow;
+};
+
+export type RankingWindowSet = {
+  readonly entries: readonly RankingWindowInput[];
+};
+
+export type TierBoardWindowSet = RankingWindowSet;
+export type ColumnWindowSet = RankingWindowSet;
+
+export type WindowedRankingScheduleEntry =
+  | {
+      readonly itemId: string;
+      readonly mode: "preset";
+      readonly settled: FrameSpan;
+    }
+  | {
+      readonly itemId: string;
+      readonly mode: "reveal";
+      readonly window: FrameSpan;
+      readonly settled: FrameSpan;
+    };
+
+export type TierBoardSchedule = {
+  readonly id: string;
+  readonly variant: "tier-board";
+  readonly outer: FrameSpan;
+  readonly entries: readonly WindowedRankingScheduleEntry[];
+};
+
+export type ColumnSchedule = {
+  readonly id: string;
+  readonly variant: "column";
+  readonly outer: FrameSpan;
+  readonly entries: readonly WindowedRankingScheduleEntry[];
+};
+
+export type RankingSchedule = TriggeredRankingSchedule | TierBoardSchedule | ColumnSchedule;
+
+export type RankingTextStyle = {
+  readonly fonts: readonly FontArtifactRef[];
+  readonly sizePx: number;
+  readonly weight: number;
+  readonly color: string;
+  readonly lineHeight: number;
+};
+
+export type RankingBoardPaint = {
+  readonly background: string;
+  readonly borderColor: string;
+  readonly borderWidthPx: number;
+  readonly radiusPx: number;
+  readonly shadow: {
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly blurPx: number;
+    readonly spreadPx: number;
+    readonly color: string;
+  };
+};
+
+export type RankingMotionStyle = {
+  readonly appearFrames: number;
+  readonly moveFrames: number;
+  readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+};
+
+export type TierBoardMotionStyle = {
+  readonly appearFrames: number;
+  readonly moveFrames: number;
+};
+
+export type RankingSoundStyle = {
+  readonly appearGain: number;
+  readonly moveGain: number;
+  readonly fadeFrames: number;
+};
+
+export type TierRowStyle = {
+  readonly id: string;
+  readonly label: string;
+  readonly color: string;
+};
+
+export type TierBoardStyle = {
+  readonly rows: readonly TierRowStyle[];
+  readonly fonts: readonly FontArtifactRef[];
+  readonly labelTextColor: string;
+  readonly labelSizeRatio: number;
+  readonly labelLineHeight: number;
+  readonly boardColor: string;
+  readonly borderColor: string;
+  readonly borderWidthPx: number;
+  readonly labelWidthRatio?: number;
+  readonly stagePoint: { readonly x: number; readonly y: number };
+  readonly stageSizePx: number;
+  readonly iconRadiusRatio: number;
+  readonly iconFit: "contain" | "cover";
+  readonly motion: TierBoardMotionStyle;
+  readonly boardStackingOrder: number;
+  readonly stageStackingOrder: number;
+  readonly itemStackingOrder: number;
+};
+
+export type ColumnStyle = {
+  readonly board: RankingBoardPaint;
+  readonly text: RankingTextStyle;
+  readonly rankColors: readonly string[];
+  readonly paddingPx: number;
+  readonly rowHeightPx: number;
+  readonly rowGapPx: number;
+  readonly iconSizePx: number;
+  readonly iconRadiusPx: number;
+  readonly iconFit: "contain" | "cover";
+  readonly stagePoint: { readonly x: number; readonly y: number };
+  readonly stageSizePx: number;
+  readonly motion: RankingMotionStyle;
+  readonly boardStackingOrder: number;
+  readonly stageStackingOrder: number;
+  readonly itemStackingOrder: number;
+};
+
+export type TopThreeStyle = {
+  readonly text: RankingTextStyle;
+  readonly slotColors: readonly string[];
+  readonly centerX: number;
+  readonly baselineY: number;
+  readonly slotGapPx: number;
+  readonly iconSizePx: number;
+  readonly iconRadiusPx: number;
+  readonly iconFit: "contain" | "cover";
+  readonly ringWidthPx: number;
+  readonly labelGapPx: number;
+  readonly motion: RankingMotionStyle;
+  readonly boardStackingOrder: number;
+  readonly itemStackingOrder: number;
+};
+
+type TierBoardItemBase = {
+  readonly variant: "tier-board";
+  readonly id: string;
+  readonly tier: string;
+  readonly stackingOrder?: number;
+};
+
+export type TierBoardItemSpec = TierBoardItemBase & (
+  | { readonly preset: true }
+  | { readonly preset: false; readonly entry: "direct" | "drop" }
+);
+
+export type ColumnItemSpec = {
+  readonly variant: "column";
+  readonly id: string;
+  readonly label: string;
+  readonly rank: number;
+  readonly preset: boolean;
+  readonly stackingOrder?: number;
+};
+
+export type TopThreeItemSpec = {
+  readonly variant: "top-three";
+  readonly id: string;
+  readonly label: string;
+  readonly stackingOrder?: number;
+};
+
+export type RankingItemSpec = TierBoardItemSpec | ColumnItemSpec | TopThreeItemSpec;
+
+/** Structural half of an Item whose visible copy arrives on a Text graph edge. */
+export type RankingTextItemShell =
+  | Omit<ColumnItemSpec, "label">
+  | Omit<TopThreeItemSpec, "label">;
+
+export type RankingItemSpecSet = {
+  readonly variant: RankingVariant;
+  readonly items: readonly RankingItemSpec[];
+};
+
+export type TierBoardItem = TierBoardItemSpec & { readonly icon: BlobRef };
+export type ColumnItem = ColumnItemSpec & { readonly icon?: BlobRef };
+export type TopThreeItem = TopThreeItemSpec & { readonly icon?: BlobRef };
+
+export type TierBoardItemSet = {
+  readonly items: readonly TierBoardItem[];
+};
+export type ColumnItemSet = {
+  readonly items: readonly ColumnItem[];
+};
+export type TopThreeItemSet = {
+  readonly items: readonly TopThreeItem[];
+};
+
+export type TierBoardProgram = {
+  readonly id: string;
+  readonly canvas: CanvasSpace;
+  readonly frame: SpatialFrame;
+  readonly schedule: TierBoardSchedule;
+  readonly style: TierBoardStyle;
+  readonly items: readonly TierBoardItem[];
+};
+export type ColumnProgram = {
+  readonly id: string;
+  readonly canvas: CanvasSpace;
+  readonly frame: SpatialFrame;
+  readonly schedule: ColumnSchedule;
+  readonly style: ColumnStyle;
+  readonly items: readonly ColumnItem[];
+};
+export type TopThreeProgram = {
+  readonly id: string;
+  readonly frame: SpatialFrame;
+  readonly schedule: TriggeredRankingSchedule;
+  readonly style: TopThreeStyle;
+  readonly items: readonly TopThreeItem[];
+};
+export type RankingProgram = TierBoardProgram | ColumnProgram | TopThreeProgram;
+
+export type RankingSoundEvent = {
+  readonly id: string;
+  readonly itemId: string;
+  readonly kind: "appear" | "move";
+  readonly frame: number;
+};
+
+export type RankingSoundEventPlan = {
+  readonly id: string;
+  readonly variant: RankingVariant;
+  readonly events: readonly RankingSoundEvent[];
+};
+
+export type RankingSoundSet = {
+  readonly appear?: SynchronizedMedia;
+  readonly move?: SynchronizedMedia;
+};

package/packages/ranking-studio/README.md

@@ -0,0 +1,3 @@
+# `@hypit/ranking-studio`
+
+Hypit Studio Companion for the Ranking module's Column, Tier and Top Three surfaces.

package/packages/ranking-studio/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@hypit/ranking-studio",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": { ".": "./src/index.ts" },
+  "hypit": { "activation": "./src/activation.ts" },
+  "dependencies": {
+    "@hypit/ranking": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*"
+  }
+}

package/packages/ranking-studio/src/activation.ts

@@ -0,0 +1,7 @@
+import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
+import { rankingStudioTrackCompanions } from "./index.js";
+
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createStudioTrackCompanionHostFacet(rankingStudioTrackCompanions)],
+};