LogicStamp compiles TypeScript source code into a structured intermediate representation (IR) — deterministic architectural contracts that describe your system's interfaces, dependencies, and composition.
This document covers all LogicStamp data structures. All schemas are versioned and validated to ensure compatibility.
LogicStamp uses semantic versioning for schemas:
| Schema | Current Version | Purpose |
|---|---|---|
UIFContract |
0.4 |
Component contract structure |
LogicStampBundle |
0.1 |
LLM context bundle format |
LogicStampIndex |
0.2 |
Main index for multi-file context |
Component contract structure embedded in bundles.
interface UIFContract {
type: "UIFContract";
schemaVersion: "0.4";
kind: "react:component" | "react:hook" | "vue:component" | "vue:composable" | "ts:module" | "node:cli" | "node:api";
description?: string;
composition: {
variables: string[];
hooks: string[];
components: string[];
functions: string[];
};
interface: {
props: Record<string, PropSignature>;
emits: Record<string, EventSignature>;
state: Record<string, StateSignature>;
};
exports?: "default" | "named" | { named: string[] }; // Optional export metadata
style?: StyleMetadata; // Optional style metadata (when --include-style is used)
nextjs?: NextJSMetadata; // Optional Next.js App Router metadata
semanticHash: string; // Format: "uif:..." (24 hex chars)
fileHash: string; // Format: "uif:..." (24 hex chars)
}
interface PropSignature {
type: string;
signature?: string; // For function props
optional?: boolean;
}
interface EventSignature {
type: string;
signature?: string; // Function signature
}
interface StateSignature {
type: string;
}
interface StyleMetadata {
styleSources?: StyleSources;
layout?: LayoutMetadata;
visual?: VisualMetadata;
animation?: AnimationMetadata;
/** Reserved: allowed by schema; not populated by `stamp context` style extraction today */
pageLayout?: PageLayoutMetadata;
}
interface StyleSources {
tailwind?: {
categories: Record<string, string[]>; // layout, spacing, colors, typography, borders, effects
breakpoints?: string[]; // sm, md, lg, xl, 2xl
classCount: number;
};
scssModule?: string; // Path to SCSS module file
scssDetails?: {
selectors: string[];
properties: string[];
features: {
variables?: boolean;
nesting?: boolean;
mixins?: boolean;
};
};
cssModule?: string; // Path to CSS module file
cssDetails?: {
selectors: string[];
properties: string[];
};
inlineStyles?: boolean | {
properties?: string[]; // CSS property names (e.g., ['animationDelay', 'color', 'padding'])
values?: Record<string, string>; // Property-value pairs for literal values (e.g., { animationDelay: '2s', color: 'blue' })
};
styledJsx?: {
css?: string; // Extracted CSS content from <style jsx> blocks
global?: boolean; // Whether the style block has global attribute
selectors?: string[]; // CSS selectors found in the extracted CSS
properties?: string[]; // CSS properties found in the extracted CSS
};
styledComponents?: {
components?: string[];
usesTheme?: boolean;
usesCssProp?: boolean;
};
motion?: {
components?: string[];
variants?: string[];
features: {
gestures?: boolean;
layoutAnimations?: boolean;
viewportAnimations?: boolean;
};
};
materialUI?: {
components?: string[];
packages?: string[];
features: {
usesTheme?: boolean;
usesSxProp?: boolean;
usesStyled?: boolean;
usesMakeStyles?: boolean;
usesSystemProps?: boolean;
};
};
antd?: {
components?: string[];
packages?: string[];
features: {
usesTheme?: boolean;
usesConfigProvider?: boolean;
usesForm?: boolean;
usesLocale?: boolean;
usesIcons?: boolean;
};
};
chakraUI?: {
components?: string[];
packages?: string[];
features: {
usesTheme?: boolean;
usesColorMode?: boolean;
usesResponsiveProps?: boolean;
usesSystemProps?: boolean;
};
};
shadcnUI?: {
components?: string[];
variants?: Record<string, string[]>;
sizes?: string[];
features: {
usesForm?: boolean;
usesTheme?: boolean;
usesIcons?: boolean;
componentDensity?: "low" | "medium" | "high";
};
};
radixUI?: {
primitives?: Record<string, string[]>;
patterns?: {
controlled?: string[];
uncontrolled?: string[];
portals?: number;
asChild?: number;
};
accessibility?: {
usesDirection?: boolean;
usesFocusManagement?: boolean;
usesKeyboardNav?: boolean;
usesModal?: boolean;
};
features?: {
primitiveCount?: number;
compositionDepth?: "simple" | "moderate" | "complex";
};
};
}
interface LayoutMetadata {
type?: "flex" | "grid" | "relative" | "absolute";
cols?: string; // Grid column pattern (e.g., "grid-cols-2 md:grid-cols-3")
hasHeroPattern?: boolean;
hasFeatureCards?: boolean;
sections?: string[];
}
interface VisualMetadata {
colors?: string[]; // Color utility classes (limited to top 10)
spacing?: string[]; // Spacing utility classes (limited to top 10)
radius?: string; // Most common border radius pattern
typography?: string[]; // Typography classes (limited to top 10)
}
interface AnimationMetadata {
type?: string; // Animation type (e.g., "fade-in", "slide")
library?: string; // "framer-motion" or "css"
trigger?: string; // Trigger type (e.g., "inView", "hover")
}
/** Shape for optional page-level layout metadata (schema-reserved; CLI does not emit yet). */
interface PageLayoutMetadata {
pageRole?: string;
sections?: string[];
ctaCount?: number;
}
interface NextJSMetadata {
isInAppDir?: boolean;
directive?: "client" | "server";
routeRole?: "page" | "layout" | "loading" | "error" | "not-found" | "template" | "default" | "route";
segmentPath?: string; // Route path derived from file structure (e.g., "/blog/[slug]", "/api/users")
metadata?: {
static?: Record<string, unknown>; // From `export const metadata = {...}`
dynamic?: boolean; // True if `export function generateMetadata()` exists
};
}{
"type": "UIFContract",
"schemaVersion": "0.4",
"kind": "react:component",
"description": "Button component for user interactions",
"composition": {
"variables": ["count"],
"hooks": ["useState"],
"components": ["Icon"],
"functions": ["handleClick"]
},
"interface": {
"props": {
"onClick": {
"type": "function",
"signature": "() => void"
},
"label": {
"type": "string",
"optional": false
}
},
"emits": {},
"state": {
"isLoading": {
"type": "boolean"
}
}
},
"semanticHash": "uif:1a27d0944bbaaf561ee05a01",
"fileHash": "uif:1f0fa0e2c8958d7fc1696036"
}| Field | Type | Required | Description |
|---|---|---|---|
type |
"UIFContract" |
✅ | Contract type identifier |
schemaVersion |
"0.4" |
✅ | Schema version for compatibility |
kind |
string |
✅ | Component type (react:component, react:hook, etc.) |
description |
string |
❌ | Human-readable description |
composition |
object |
✅ | Structural composition |
composition.variables |
string[] |
✅ | Named variables in component |
composition.hooks |
string[] |
✅ | React hooks used |
composition.components |
string[] |
✅ | Child components used |
composition.functions |
string[] |
✅ | Named functions defined |
interface |
object |
✅ | Public API contract |
interface.props |
object |
✅ | Component props |
interface.emits |
object |
✅ | Component events |
interface.state |
object |
✅ | Component state |
exports |
string | object |
❌ | Export metadata: "default", "named", or { named: string[] } |
style |
StyleMetadata |
❌ | Style metadata (only when --include-style is used) |
nextjs |
NextJSMetadata |
❌ | Next.js App Router metadata (route roles, segment paths, metadata exports) |
semanticHash |
string |
✅ | Logic-based hash (uif:...) |
fileHash |
string |
✅ | Content-based hash (uif:...) |
The style field is only included when using stamp context style or stamp context --include-style. It provides visual and layout information extracted from components.
Identifies which styling approaches are used:
tailwind- Tailwind CSS utility classes, categorized by type (layout, spacing, colors, typography, borders, effects) with breakpoint informationscssModule/cssModule- Path to imported SCSS/CSS module filescssDetails/cssDetails- Parsed details from style files (selectors, properties, SCSS features)inlineStyles- Inline style usage. Can beboolean(legacy format) or an object with:properties: Array of CSS property names (e.g.,['animationDelay', 'color', 'padding'])values: Record of property-value pairs for literal values (e.g.,{ animationDelay: '2s', color: 'blue' })
styledJsx- Styled JSX CSS content extracted from<style jsx>blocks:css: Extracted CSS content stringglobal: Boolean indicating if the style block hasglobalattributeselectors: Array of CSS selectors found in the extracted CSSproperties: Array of CSS properties found in the extracted CSS
styledComponents- Styled-components/Emotion usage with component names and theme informationmotion- Framer Motion usage with components, variants, and feature flagsmaterialUI- Material UI usage with components, packages, and styling features (theme, sx prop, styled, makeStyles, system props)antd- Ant Design usage with components, packages, and features (theme, ConfigProvider, form, locale, icons)chakraUI- Chakra UI usage with components, packages, and features (theme, color mode, responsive props, system props)shadcnUI- ShadCN/UI usage with components, variants, sizes, and features (form integration, theme, icons, component density)radixUI- Radix UI usage with primitives, patterns, accessibility features, and composition complexity
Structural layout information:
type- Layout type: "flex", "grid", "relative", or "absolute"cols- Grid column pattern (e.g., "grid-cols-2 md:grid-cols-3")hasHeroPattern- Boolean indicating hero section pattern (large text + CTA buttons)hasFeatureCards- Boolean indicating feature card grid patternsections- Array of identified page sections
Visual design patterns:
colors- Array of color utility classes (sorted, limited to top 10)spacing- Array of spacing utility classes (sorted, limited to top 10)radius- Most common border radius patterntypography- Array of typography classes (sorted, limited to top 10)
Animation and motion information:
library- Animation library: "framer-motion" or "css"type- Animation type (e.g., "fade-in", "slide")trigger- Trigger type (e.g., "inView", "hover", "click")
Not populated by stamp context today. Present in the schema and TypeScript types for forward compatibility and manual or future tooling.
When present, the intended fields are:
pageRole- Page role (e.g., "landing", "dashboard")sections- Array of page sectionsctaCount- Number of call-to-action elements
Note: Style metadata is only included when style information is detected. Components without style usage will not have a style field.
See style.md for comprehensive documentation on style metadata extraction.
The nextjs field is only included for Next.js App Router files. It provides Next.js-specific information:
isInAppDir- Whether the file is in the/app/directorydirective-'use client'or'use server'directiverouteRole- Route role:page,layout,loading,error,not-found,template,default, orroutesegmentPath- Route path derived from file structure (e.g.,/blog/[slug],/api/users)metadata- Next.js metadata exports:static- Static metadata fromexport const metadata = {...}dynamic- Boolean indicating ifexport function generateMetadata()exists
Note: Next.js metadata is only included for files in Next.js projects. Non-Next.js files will not have a nextjs field.
See nextjs.md for comprehensive documentation on Next.js support.
LLM context bundle containing a dependency graph and contracts.
interface LogicStampBundle {
$schema?: string; // Optional JSON Schema reference
position?: string; // Human-readable position (e.g., "1/5")
type: "LogicStampBundle";
schemaVersion: "0.1";
entryId: string; // Path to root component
depth: number; // Dependency traversal depth
createdAt: string; // ISO 8601 timestamp
bundleHash: string; // Format: "uifb:..." (24 hex chars)
graph: {
nodes: BundleNode[];
edges: BundleEdge[];
};
meta: {
missing: MissingDependency[];
source: string; // Tool version (e.g., "logicstamp-context@0.4.x")
};
}
interface BundleNode {
entryId: string;
contract: UIFContract;
codeHeader?: string; // @uif header block (if --include-code header)
code?: string; // Full source code (if --include-code full)
}
interface BundleEdge {
[0]: string; // Source entryId
[1]: string; // Target entryId
}
interface MissingDependency {
name: string;
reason: "external package" | "file not found" | "outside scan path" | "max depth exceeded" | "circular dependency";
referencedBy?: string; // Component that imports it
packageName?: string; // Extracted package name for third-party dependencies
packageVersion?: string; // Version from package.json (if available)
}{
"$schema": "https://logicstamp.dev/schemas/context/v0.1.json",
"position": "1/5",
"type": "LogicStampBundle",
"schemaVersion": "0.1",
"entryId": "src/components/Button.tsx",
"depth": 1,
"createdAt": "2025-01-15T10:30:00.000Z",
"bundleHash": "uifb:abc123e4f99aa01deef02bb1",
"graph": {
"nodes": [
{
"entryId": "src/components/Button.tsx",
"contract": {
"type": "UIFContract",
"schemaVersion": "0.4",
"kind": "react:component",
"description": "Button component",
"composition": {
"variables": [],
"hooks": ["useState"],
"components": [],
"functions": ["Button"]
},
"interface": {
"props": {
"onClick": {
"type": "function",
"signature": "() => void"
}
},
"emits": {},
"state": {}
},
"exports": "default",
"semanticHash": "uif:1a27d0944bbaaf561ee05a01",
"fileHash": "uif:1f0fa0e2c8958d7fc1696036",
"style": {
"styleSources": {
"tailwind": {
"categories": {
"layout": ["flex", "flex-col", "items-center"],
"spacing": ["py-4", "px-6", "gap-2"],
"colors": ["bg-blue-500", "text-white"],
"typography": ["text-lg", "font-semibold"]
},
"breakpoints": ["md", "lg"],
"classCount": 8
},
"materialUI": {
"components": ["Button"],
"packages": ["@mui/material"],
"features": {
"usesSxProp": true
}
}
},
"layout": {
"type": "flex",
"hasHeroPattern": false
},
"visual": {
"colors": ["bg-blue-500", "text-white"],
"spacing": ["py-4", "px-6"],
"radius": "md"
}
}
},
"codeHeader": "/** @uif Contract ... */"
}
],
"edges": []
},
"meta": {
"missing": [
{
"name": "@mui/material",
"reason": "external package",
"referencedBy": "src/components/Button.tsx"
}
],
"source": "logicstamp-context@0.5.x"
}
}| Field | Type | Required | Description |
|---|---|---|---|
$schema |
string |
❌ | JSON Schema reference URL |
position |
string |
❌ | Human-readable position (e.g., "1/5") |
type |
"LogicStampBundle" |
✅ | Bundle type identifier |
schemaVersion |
"0.1" |
✅ | Schema version |
entryId |
string |
✅ | Path to root component |
depth |
number |
✅ | Dependency traversal depth used |
createdAt |
string |
✅ | ISO 8601 timestamp |
bundleHash |
string |
✅ | Bundle-level hash (uifb:...) |
graph |
object |
✅ | Dependency graph |
graph.nodes |
BundleNode[] |
✅ | Components in bundle |
graph.nodes[].entryId |
string |
✅ | Component identifier |
graph.nodes[].contract |
UIFContract |
✅ | Component contract |
graph.nodes[].codeHeader |
string | null |
❌ | Header comment (when --include-code header) |
graph.nodes[].code |
string | null |
❌ | Full source code (when --include-code full) |
graph.edges |
BundleEdge[] |
✅ | Dependencies between components |
meta |
object |
✅ | Bundle metadata |
meta.missing |
MissingDependency[] |
✅ | Unresolved dependencies |
meta.source |
string |
✅ | Tool version string |
Main index file for multi-file context organization.
interface LogicStampIndex {
type: "LogicStampIndex";
schemaVersion: "0.2";
projectRoot: string; // Relative path (usually ".")
projectRootResolved?: string; // Optional absolute path (deprecated, omitted in v0.3.2+ for portability)
createdAt: string; // ISO 8601 timestamp
summary: {
totalComponents: number;
totalBundles: number;
totalFolders: number;
totalTokenEstimate: number;
};
folders: FolderEntry[];
meta: {
source: string; // Tool version
};
}
interface FolderEntry {
path: string; // Relative path from project root
contextFile: string; // Path to this folder's context.json
bundles: number; // Number of bundles in this folder
components: string[]; // Component file names
isRoot: boolean; // Whether this is an entry point
rootLabel?: string; // Label for root folders
tokenEstimate: number; // Estimated token count
}{
"type": "LogicStampIndex",
"schemaVersion": "0.2",
"projectRoot": ".",
"createdAt": "2025-01-15T10:30:00.000Z",
"summary": {
"totalComponents": 42,
"totalBundles": 15,
"totalFolders": 5,
"totalTokenEstimate": 13895
},
"folders": [
{
"path": "src/components",
"contextFile": "src/components/context.json",
"bundles": 3,
"components": ["Button.tsx", "Card.tsx"],
"isRoot": false,
"tokenEstimate": 5234
},
{
"path": ".",
"contextFile": "context.json",
"bundles": 2,
"components": ["App.tsx"],
"isRoot": true,
"rootLabel": "Project Root",
"tokenEstimate": 2134
}
],
"meta": {
"source": "logicstamp-context@0.5.x"
}
}| Field | Type | Required | Description |
|---|---|---|---|
type |
"LogicStampIndex" |
✅ | Index type identifier |
schemaVersion |
"0.2" |
✅ | Schema version |
projectRoot |
string |
✅ | Relative project root path |
projectRootResolved |
string |
Optional absolute project root path (deprecated, omitted in v0.3.2+ for portability) | |
createdAt |
string |
✅ | ISO 8601 timestamp |
summary |
object |
✅ | Project-wide statistics |
summary.totalComponents |
number |
✅ | Total components analyzed |
summary.totalBundles |
number |
✅ | Total bundles generated |
summary.totalFolders |
number |
✅ | Total folders with context files |
summary.totalTokenEstimate |
number |
✅ | Estimated total tokens |
folders |
FolderEntry[] |
✅ | Folder metadata entries |
folders[].path |
string |
✅ | Relative folder path |
folders[].contextFile |
string |
✅ | Path to folder's context.json |
folders[].bundles |
number |
✅ | Number of bundles in folder |
folders[].components |
string[] |
✅ | Component file names |
folders[].isRoot |
boolean |
✅ | Whether folder is entry point |
folders[].rootLabel |
string |
❌ | Label for root folders |
folders[].tokenEstimate |
number |
✅ | Estimated tokens for folder |
meta |
object |
✅ | Index metadata |
meta.source |
string |
✅ | Tool version string |
All hashes in LogicStamp follow consistent formats:
- Format:
uif:+ 24 hex characters - Example:
uif:1a27d0944bbaaf561ee05a01 - Based on: Component logic and contract structure
- Changes when: Props, events, state, or structural footprint changes
- Format:
uif:+ 24 hex characters - Example:
uif:1f0fa0e2c8958d7fc1696036 - Based on: Raw file content (excluding @uif headers)
- Changes when: Any file content modification
- Format:
uifb:+ 24 hex characters - Example:
uifb:abc123e4f99aa01deef02bb1 - Based on: Bundle structure (nodes, depth, schema version)
- Changes when: Any component's semantic hash changes, or bundle structure changes
See hashes.md for detailed information about hash computation.
LogicStamp performs automatic runtime validation when loading sidecar .uif.json contract files using AJV. This ensures that:
- Malformed or corrupted contract files are caught immediately
- Outdated contracts (wrong
schemaVersion) are rejected - Unexpected fields are detected (schema uses
additionalProperties: false) - Type mismatches are reported with clear error messages
Invalid contracts return null from loadContract() with detailed errors logged via debugError(). Enable debug logging to see validation errors:
LOGICSTAMP_DEBUG=1 stamp contextAll schemas can also be validated explicitly using stamp context validate:
# Validate all context files (multi-file mode)
stamp context validate
# Validate a specific file
stamp context validate src/components/context.jsonThe validator checks:
- Required fields are present
- Field types match schema
- Schema versions are correct
- Hash formats are valid
- Structure matches expected shape
Schemas are versioned to support evolution:
- Major version changes – Breaking changes requiring migration
- Minor version changes – New optional fields, backward compatible
- Patch version changes – Bug fixes, fully backward compatible
When schema versions change:
- Old versions remain supported for reading
- New versions are generated for writing
- Validation warns on unexpected versions
LogicStamp bundles can include $schema references for IDE validation:
{
"$schema": "https://logicstamp.dev/schemas/context/v0.1.json",
"type": "LogicStampBundle",
// ...
}This enables:
- IDE autocomplete and validation
- JSON Schema validation tools
- Type checking in editors
- uif_contracts.md – Detailed UIF contract documentation
- hashes.md – Hash computation and formats
- validate.md – Schema validation guide
- usage.md – How to generate context files