sculpted 0.3.0 → 0.3.1

package/README.md

@@ -117,13 +117,10 @@ instead of pretending the full cascade can be edited safely.
 
 ## Documentation
 
-- [Vite plugin options](docs/vite-plugin.md) covers setup, defaults, endpoint configuration, and
-  dev/prod behavior.
+- [Vite plugin options](docs/vite-plugin.md) covers setup, defaults, and dev/prod behavior.
 - [Source writeback](docs/source-writeback.md) covers the safety model, supported edit shapes, and
   common failure modes.
-- [Source syntax adapters](docs/source-syntax-adapters.md) covers TSRX and custom parser adapters.
-- [Example apps](docs/examples.md) covers the React and Preact Panda CSS examples used for manual
-  verification.
+- [Source syntax adapters](docs/source-syntax-adapters.md) covers opt-in TSRX support.
 
 ## Troubleshooting
 

package/dist/vite.d.mts

@@ -9,12 +9,8 @@ type InspectorVitePluginOptions = {
   readonly panda?: {
     readonly configPath?: string;
     readonly cssImportSources?: readonly string[];
-    readonly recipeImportSources?: readonly string[];
-    readonly cssFunctionNames?: readonly string[];
-    readonly cxFunctionNames?: readonly string[];
   };
   readonly manifest?: {
-    readonly outFile?: string;
     readonly virtualEndpoint?: string;
   };
   readonly metadata?: {
@@ -22,13 +18,6 @@ type InspectorVitePluginOptions = {
   };
   readonly runtime?: {
     readonly inject?: boolean;
-    readonly globalName?: string;
-  };
-  readonly attributes?: {
-    readonly editId?: string;
-    readonly source?: string;
-    readonly jsxSource?: string;
-    readonly component?: string;
   };
   readonly sourceSyntax?: SourceSyntaxOption;
 };

package/dist/vite.mjs

@@ -1,4 +1,4 @@
-import { _ as markerClassForEditId, c as DEFAULT_OPEN_SOURCE_ENDPOINT, d as DEFAULT_TOKEN_WRITEBACK_ENDPOINT, f as DEFAULT_WRITEBACK_ENDPOINT, p as SCULPTED_EVENTS, u as DEFAULT_STYLE_MODULE_ENDPOINT } from "./protocol-D5heR2QM.mjs";
+import { _ as markerClassForEditId, a as DEFAULT_JSX_SOURCE_ATTRIBUTE, c as DEFAULT_OPEN_SOURCE_ENDPOINT, d as DEFAULT_TOKEN_WRITEBACK_ENDPOINT, f as DEFAULT_WRITEBACK_ENDPOINT, l as DEFAULT_SOURCE_ATTRIBUTE, p as SCULPTED_EVENTS, r as DEFAULT_EDIT_ID_ATTRIBUTE, t as DEFAULT_COMPONENT_ATTRIBUTE, u as DEFAULT_STYLE_MODULE_ENDPOINT } from "./protocol-D5heR2QM.mjs";
 import { S as resolveSourceParserAdapter, _ as analyzePandaCssSource, a as createStyleModuleSourcePatch, b as parsePandaSource, c as resolveProjectPath, d as toRelativeProjectPath$1, f as trustedManifestFilePath, g as createInlineCssSourcePatch, h as createStaticCssPatch, i as createStyleModuleDetachPatch, l as safeProjectSourcePath, m as createStaticCssBatchPatch, n as componentStyleModulePaths, o as readComponentStyleModule, p as trustedTokenSourceFilePath, r as createStyleModuleAttachPatch, s as normalizePath$1, t as createTokenConfigPatch, u as stripViteQuery, v as hashSource } from "./patcher-DQgKdozw.mjs";
 import ts from "typescript";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
@@ -998,7 +998,6 @@ function registerRuntimeModuleRoutes(server, options) {
 		response.end(runtimeBootstrapSource({
 			manifestEndpoint: options.manifestEndpoint,
 			editorMetadataEndpoint: options.editorMetadataEndpoint,
-			globalName: options.globalName,
 			runtimeModuleEndpoint: options.runtimeModuleEndpoint,
 			uiModuleEndpoint: options.uiModuleEndpoint
 		}));
@@ -1084,7 +1083,6 @@ function registerRuntimeModuleRoutes(server, options) {
 }
 function runtimeBootstrapSource(options) {
 	const runtimeOptions = JSON.stringify({
-		globalName: options.globalName,
 		manifestEndpoint: options.manifestEndpoint,
 		editorMetadataEndpoint: options.editorMetadataEndpoint
 	});
@@ -2189,10 +2187,10 @@ function sculpted(options = {}) {
 	const uiModuleEndpoint = DEFAULT_UI_MODULE_ENDPOINT;
 	const runtimeChunkEndpoint = DEFAULT_RUNTIME_CHUNK_ENDPOINT;
 	const attributes = {
-		editId: options.attributes?.editId ?? "data-sculpted-edit-id",
-		source: options.attributes?.source ?? "data-sculpted-source",
-		jsxSource: options.attributes?.jsxSource ?? "data-sculpted-jsx-source",
-		component: options.attributes?.component ?? "data-sculpted-component"
+		editId: DEFAULT_EDIT_ID_ATTRIBUTE,
+		source: DEFAULT_SOURCE_ATTRIBUTE,
+		jsxSource: DEFAULT_JSX_SOURCE_ATTRIBUTE,
+		component: DEFAULT_COMPONENT_ATTRIBUTE
 	};
 	let projectRoot = normalizePath$1(options.projectRoot ?? "");
 	let devEnabled = options.enabled !== false;
@@ -2273,7 +2271,6 @@ function sculpted(options = {}) {
 			registerRuntimeModuleRoutes(nextServer, {
 				manifestEndpoint: endpoint,
 				editorMetadataEndpoint,
-				globalName: options.runtime?.globalName,
 				runtimeBootstrapEndpoint,
 				runtimeModuleEndpoint,
 				uiModuleEndpoint,

package/docs/examples.md

@@ -1,7 +1,7 @@
 # Example Apps
 
-Sculpted includes minimal Vite + Panda CSS apps for manually verifying inspector behavior and source
-writeback while the package is being built.
+Sculpted includes minimal Vite + Panda CSS apps for contributors who need to manually verify
+inspector behavior and source writeback while developing the package.
 
 ## React
 
@@ -26,5 +26,5 @@ pnpm install
 pnpm dev
 ```
 
-Use these apps to verify supported edits, unsupported read-only cases, token creation checks, React
-`className`, Preact `class`, TSRX parsing, and production-dark behavior while developing Sculpted.
+These apps intentionally include edge cases and maintainer-focused checks. Most users should start
+with the setup examples in the main README instead.

package/docs/source-syntax-adapters.md

@@ -1,13 +1,8 @@
 # Source Syntax Adapters
 
-Sculpted can support non-standard source syntax when a parser adapter exposes stable ranges into
-the original authoring source. The patcher edits that original file directly after revalidating
-hashes, source containment, and AST shape.
-
-Sourcemaps are not the writeback authority. A future fallback may use sourcemaps to explain
-generated-code provenance, but safe writes still require an original-source parser and patchable
-target. If the adapter cannot provide stable original ranges for a source shape, Sculpted should
-report that target as read-only.
+Sculpted can support non-standard source syntax when that syntax can be parsed back to stable
+locations in the original authoring file. Unsupported source shapes are shown as read-only instead
+of guessed.
 
 ## TSRX Support
 
@@ -30,17 +25,6 @@ export default defineConfig({
 })
 ```
 
-When a config imports more than one syntax adapter, alias the TSRX export at the import site:
-
-```ts
-import { sourceSyntax as tsrx } from 'sculpted/tsrx'
-
-sculpted({
-  include: ['src/**/*.{ts,tsx,tsrx,view}'],
-  sourceSyntax: [tsrx, customViewSyntax],
-})
-```
-
 The supported TSRX authoring shape is a TSRX component with a static Panda `css({ ... })` object:
 
 ```ts
@@ -56,38 +40,11 @@ export function Card() {
 TSRX support covers:
 
 - static `css({ ... })` object literal analysis;
-- marker-class instrumentation for element selection;
-- existing literal `set` writeback after re-parsing the original `.tsrx` source.
+- element selection in the inspector;
+- saving edits to existing literal values in the original `.tsrx` source.
 
 TSRX support does not cover:
 
-- direct `data-panda-*` metadata insertion;
 - inline source creation;
 - add, delete, or rename operations;
-- generated TSX or sourcemap-based writeback authority.
-
-## Custom Adapters
-
-Languages that can expose original source ranges can opt into the same writeback lane with a
-`sourceSyntax` parser adapter. The option accepts one adapter or an ordered adapter list.
-
-```ts
-sculpted({
-  include: ['src/**/*.view'],
-  sourceSyntax: {
-    languageId: 'my-tsx-superset',
-    kind: 'typescript',
-    isSupportedFile: (file) => file.endsWith('.view'),
-    parse({ filePath, sourceText }) {
-      return {
-        kind: 'typescript',
-        languageId: 'my-tsx-superset',
-        sourceFile: parseToTypeScriptCompatibleSourceFile(filePath, sourceText),
-      }
-    },
-  },
-})
-```
-
-Parser adapters must expose node ranges as offsets into the original authoring source text. Use
-read-only failures for any syntax that cannot provide stable original ranges for a source shape.
+- generated TSX or sourcemap-based writeback.

package/docs/source-writeback.md

@@ -31,17 +31,12 @@ Sculpted does not edit:
 
 ## Safety Model
 
-Source writes are revalidated on the dev server before writing:
+Source writes are revalidated on the dev server before writing. Sculpted only writes to files inside
+the configured project root, re-checks the current source before saving, and rejects stale source,
+unsupported shapes, duplicate keys, parser errors, and unsafe paths.
 
-- the browser sends manifest edit IDs, not trusted file paths;
-- the server resolves edit IDs through the trusted manifest;
-- the patcher re-reads source and validates project-root containment;
-- stale source hashes, unsupported source shapes, duplicate keys, parse errors, and path escapes are
-  rejected;
-- batched saves apply same-file edits against one source snapshot before writing.
-
-The UI saves immediately after clicking Save. The writeback endpoint still supports dry-run patch
-responses with focused diffs for tests and tooling.
+The UI saves immediately after clicking Save. If a save cannot be applied confidently, Sculpted
+shows the failure instead of guessing at a source edit.
 
 ## Supported Edit Example
 

package/docs/vite-plugin.md

@@ -68,12 +68,8 @@ type InspectorVitePluginOptions = {
   readonly panda?: {
     readonly configPath?: string
     readonly cssImportSources?: readonly string[]
-    readonly recipeImportSources?: readonly string[]
-    readonly cssFunctionNames?: readonly string[]
-    readonly cxFunctionNames?: readonly string[]
   }
   readonly manifest?: {
-    readonly outFile?: string
     readonly virtualEndpoint?: string
   }
   readonly metadata?: {
@@ -81,13 +77,6 @@ type InspectorVitePluginOptions = {
   }
   readonly runtime?: {
     readonly inject?: boolean
-    readonly globalName?: string
-  }
-  readonly attributes?: {
-    readonly editId?: string
-    readonly source?: string
-    readonly jsxSource?: string
-    readonly component?: string
   }
   readonly sourceSyntax?: SourceSyntaxOption
 }
@@ -169,12 +158,6 @@ sculpted({
 })
 ```
 
-### Reserved Panda Options
-
-`panda.recipeImportSources`, `panda.cssFunctionNames`, and `panda.cxFunctionNames` are part of the
-public option type but are not wired into the Vite plugin implementation. Recipes, patterns,
-`cva()`, and broader function-name customization are not supported.
-
 ### `manifest.virtualEndpoint`
 
 Defaults to `/@sculpted/manifest`.
@@ -190,10 +173,6 @@ sculpted({
 })
 ```
 
-### `manifest.outFile`
-
-Reserved. The option is typed but not wired into the Vite plugin implementation.
-
 ### `metadata.virtualEndpoint`
 
 Defaults to `/@sculpted/editor-metadata`.
@@ -223,46 +202,10 @@ sculpted({
 })
 ```
 
-### `runtime.globalName`
-
-Overrides the browser global name used by the installed runtime.
-
-```ts
-sculpted({
-  runtime: {
-    globalName: '__mySculptedRuntime',
-  },
-})
-```
-
-### `attributes`
-
-Overrides the DOM attributes used for inspector metadata.
-
-Defaults:
-
-- `editId`: `data-sculpted-edit-id`
-- `source`: `data-sculpted-source`
-- `jsxSource`: `data-sculpted-jsx-source`
-- `component`: `data-sculpted-component`
-
-Use these only when the defaults collide with app-specific tooling.
-
-```ts
-sculpted({
-  attributes: {
-    editId: 'data-dev-edit-id',
-    source: 'data-dev-source',
-    jsxSource: 'data-dev-jsx-source',
-    component: 'data-dev-component',
-  },
-})
-```
-
 ### `sourceSyntax`
 
-Adds one source parser adapter, or an ordered list of adapters, for non-standard source syntax that
-can expose original source ranges. See [source syntax adapters](source-syntax-adapters.md).
+Adds source parsing support for non-standard source syntax. Sculpted currently documents this for
+the bundled TSRX adapter. See [source syntax adapters](source-syntax-adapters.md).
 
 ```ts
 import { sourceSyntax } from 'sculpted/tsrx'
@@ -273,30 +216,8 @@ sculpted({
 })
 ```
 
-If the config combines multiple adapters, alias the TSRX export where it is imported:
-
-```ts
-import { sourceSyntax as tsrx } from 'sculpted/tsrx'
-
-sculpted({
-  include: ['src/**/*.{ts,tsx,tsrx,view}'],
-  sourceSyntax: [tsrx, customViewSyntax],
-})
-```
-
-## Endpoint Defaults
-
-These endpoint defaults are fixed unless an option above says otherwise:
-
-- Manifest: `/@sculpted/manifest`
-- Editor metadata: `/@sculpted/editor-metadata`
-- Source writeback: `/@sculpted/writeback`
-- Token writeback: `/@sculpted/token-writeback`
-- Open source location: `/@sculpted/open-source`
-- Style module route: `/@sculpted/style-module`
-- Runtime bootstrap: `/@sculpted/runtime`
-- Runtime module: `/@sculpted/runtime-module`
-- UI module: `/@sculpted/ui-module`
+## Development Routes
 
-The writeback, token writeback, open-source, style-module, and runtime module endpoints are internal
-runtime contracts today. They are listed here so local tooling can avoid route collisions.
+Sculpted reserves development-only routes under `/@sculpted/*`. The manifest and editor metadata
+routes can be customized with `manifest.virtualEndpoint` and `metadata.virtualEndpoint`; other
+routes are internal runtime details and should not be treated as public integration points.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sculpted",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Experimental alpha dev inspector for editing Panda CSS styles and writing safe source updates.",
   "license": "FSL-1.1-ALv2",
   "author": "Alec Larson",